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源码 在 github 上 
Vert.x Core 提 供 的 功能 : 


e 编写 TCP 客 户 端 和 服务 器 

。 编写 HTTP. 客户 端 和 服务 器 包括 Websocket 支持 
。 事件 总 线 (Event bus) 

e. 共享 的 数据 -本 地 的 map 和 分 布 式 的 map 
e 定时 和 延 时 运行 

。 部 署 和 非 部 署 Verticles 

e Sockets 

e DNS € P 3 

e 文件 系统 

@ 高 可 用 性 

e 集群 


Vert.X 核 心 功能 是 相当 简单 的 一 一 你 不 会 找到 数据 库 访 问 、 授 权 或 高 级 别 web 功能 等 ， 这 
些 东 西 你 可 以 在 哪里 找到 ? 在 这 里 -，Vert.x ext( 扩 展 ) 。 


Vertx core 非常 小 ， 非 常 轻 量 级 。 只 是 使 用 你 想 要 的 部 分 。 也 是 完全 可 嵌入 在 您 现 有 的 应 用 
程序 一 一 不 强迫 你 使 用 特殊 方式 架构 您 的 应 用 程序 ， 这 样 你 可 以 方向 使 用 Vert.x。 


您 可 以 使 用 任何 Vert.x 支持 的 其 他 语言 的 核心 。 这 有 点 小 酷 -我 们 不 强迫 你 使 用 Java API > 
JavaScript 或 者 Ruby 等 都 没 问题 一 一 毕竟 ， 不 同 的 语言 有 不 同 的 习惯 和 语法 ， 迫 使 Ruby 
开发 人 员 使 用 Java 的 语法 ， 这 会 很 奇怪 ( 举 个 例子 )。 相 反 ， 我 们 自动 生成 以 Java Api 为 核 
心 ， 等 效 、 地 道 的 每 种 语言 。 


从 现在 起 我 们 会 使 用 core 指 Vert.x core ° 


如 果 你 使 用 Maven 或 Gradle， 需 要 增加 以 下 依赖 才能 使 用 Vert.x Core API: 


e Maven (在 你 的 pom.xml 中 增加 ): 

<dependency> 
<groupId>io.vertx</groupId> 
<artifactId>vertx-core</artifactId> 


<version>3.2.0</version> 
</dependency> 


。 Gradle (在 您 的 build.gradle 文 件 增 加 ): 
compile io.vertx:vertx-core:3.2.0 


下 面 让 我 们 来 讨论 core 的 不 同 概念 和 功能 。 
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从 Vert.X 开 始 


注意 : 这 大 部 分 是 Java 特 有 的 -需要 语言 特有 的 调用 方法 


如 


78 


没有 获得 Vertx 对 象 ，Vert.x 做 不 了 什么 


Vertx 对 象 是 Vert.x 的 控制 中 心 ， 几 乎 可 以 做 所 有 事 ， 包 括 创 建 客户 端 和 服务 器 ， 获 取 引 用 到 
事件 总 线 (event bus) 、 设 置 计 时 器 等 


所 以 怎么 获得 Vertx 实 例 ? 


de X CAREAT Vert.x， 然 后 只 需 创建 一 个 实例 ， 如 下 所 示 : 


Vertx vertx = Vertx.vertx(); 


如 果 使 用 Verticles 

注意 :大 多 数 应 用 程序 只 需要 一 个 单一 的 Vert.x 实例 ， 但 如 果 你 需要 ， 可 以 创建 多 个 Vert.x È 
例 ， 例 如 ， 事 件 总 线 或 不 同 的 服务 器 和 客户 端 之 间 的 隔离 。 

创建 一 个 指定 选项 的 Vertx 3t 2 


创建 一 个 Vertx 对 象 时 ， 如 果 上 默认 值 不 是 正确 的 选择 ， 你 还 可 以 指定 选项 : 


Vertx vertx = Vertx.vertx(new VertxOptions().setWorkerPoolSize(40)); 


VertxOptions 对 象 有 许多 设置 ， 可 以 配置 集群 、 高 可 用 性 、 池 的 大 小 等 。 所 有 设置 细节 在 
Javadoc 中 有 描述 。 
创建 群集 Vert.x 对 象 


Mi | 建 clustered (群集 ) Vert.x (更 多 集群 相关 的 请 参阅 事件 总 线 ( event bus) )， 
然后 通常 会 使 用 异步 方式 创建 Vertx 对 象 。 


这 是 因为 不 同 的 Vertx 实例 在 群集 中 组 合 在 一 起 ， 通 常 需要 一 些 时 间 (也 许 几 秒 钟 ) 的 。 在 这 
段 时 间 ， 我 们 不 想 阻 止 调 用 线程 ， 所 以 我 们 把 结果 以 异步 方式 给 你 。 
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从 Vert.x 开 始 


Lb L 8 

A ze IN eB) ? 

你 可 能 注意 到 ， 在 前 面 使 用 fluent API (fluent API : 流 APl， 更 易 使 用 的 APl， 也 称 傻瓜 式 
API) 的 例子 。 


fluent API 是 支持 链 式 调用 的 。 例 如 : 


request.response().putHeader("Content-Type", "text/plain").write("some text").end(); 


整个 Vert.x Api 都 是 这 种 模式 ，， 所 以 要 去 适应 它 。 


可 以 链 式 编写 代码 ， 当 然 你 也 可 以 按 自己 的 喜欢 ， 写 上 这 样 的 代码 : 


HttpServerResponse response = request.response( ); 
response.putHeader("Content-Type", "text/plain"); 
response.write("some text"); 

response.end(); 
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不 要 call (调用 、 打 电话 ) 我 们 ， 我 们 会 call 给 


你 。 


Vert.x Api 是 很 大 程度 上 由 事件 驱动 的 。 这 意味 着 ， 当 事情 发 生 在 你 感 兴趣 的 Vert.X，Vert.X 
会 通过 回调 方式 向 您 发 送 events。 


一 些 示例 events: 


e 计时 器 激活 
Socket 收 到 数据 

从 磁盘 读 取 数 据 

发 生 了 异常 

HTTP 服务 器 收 到 请 求 


通过 向 Vert.x Api 提供 处 理 程序 来 处 理事 件 。 例 如 要 接收 一 个 计时 器 事件 每 一 秒 你 会 做 : 


vertx.setPeriodic(1000, id -> ( 
// This handler will get called every second 
System.out.println("timer fired!"); 


3); 


或 接收 到 HTTP 35 3: 


server.requestHandler(request -> { 
// This handler will be called every time an HTTP request is received at the server 
request.response().end("hello world!"); 


3); 


一 段 时 间 后 当 Vert.x 有 一 个 事件 ， 它 将 传递 到 您 的 处 理 程 序 Vert.x 将 它 异 步调 用 . 
这 将 引导 我 们 进入 Vert.x 中 的 一 些 重要 概念 : 
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He e 
不 要 阻塞 我 | 
除了 极 少数 例外 (一 些 文件 系统 操作 的 “同步 "结束 )， 没 有 一 个 Vert.x Api 阻塞 调用 线程 。 


如 果 可 以 立即 提供 的 结果 ， 它 将 立即 返回 ， 你 通常 会 提供 一 个 handle 来 接收 过 一 段 时 间 的 事 
件 。 


由 于 Vert.x API 没 有 任何 阻塞 的 线程 ， 这 意味 着 你 可 以 使 用 Vert.X 来 处 理 只 是 使 用 小 数目 线程 
的 大 量 并 发 。 


常规 阻塞 API 使 用 线程 可 能 会 阻塞 : 


e 从 socket 读 取 数 据 
e 向 磁盘 写 入 数据 
e 向 收 件 人 发 送 一 条 消息 ， 等 待 答 复 。 


e. n 
在 所 有 上 述 情况 下 ， 当 您 的 线程 正在 等 待 结果 时 它 不 能 做 别 的 -这 是 实际 上 是 浪费 。 


这 意味 着 ， 如 果 你 需要 大 量 的 并 发 使 用 阻塞 APls， 然 后 你 需要 大 量 的 线程 ， 以 防止 您 的 应 用 
程序 停止 工作 。 


线程 在 他 们 所 需要 的 内 存 (例如 栈 ) 和 上 下 文 切换 方面 有 开销 。 
对 于 许多 现代 应 用 程序 所 需要 的 并 发 水 平 ， 阻 塞 的 方法 不 能 按 比例 缩放 。 
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Reactor? 2 Reactor 


之 前 提 到 Vert.x API 是 事件 驱动 - 当 他 们 都 可 用 时 ，Vert.X 传 递 事件 给 处 理 程序 。 
在 大 多 数 情况 下 Vertx 要 求 使 用 一 种 称 为 event loop 线 程 的 处 理 程序 。 


如 无 有 Vert.x 或 您 的 应 用 程序 块 中 ，event loop 可 以 欢快 地 运行 将 事件 传递 给 不 同 的 处 理 程序 
提供 事件 陆续 到 达 


因为 没有 阻塞 ，event loop 可 以 在 短 时 间 内 提供 大 量 的 事件 。 例 如 一 个 单一 的 event loop 可 以 
非常 迅速 地 处 理 成 千 上 万 的 HTTP 请 求 。 


我 们 把 这 个 叫做 反应 器 模式 (Reactor Pattern) . 
你 可 能 会 有 之 前 听 说 过 -例如 Node.js 实现 此 模式 。 
标准 的 Reactor 所 有 事件 都 运行 在 单一 事件 循环 线程 。 


单个 线程 的 麻烦 是 在 任何 一 个 时 间 它 只 能 运行 在 单一 的 核心 上 (例如 Nodejs 应 用 ， 如 果 想 要 
实现 多 线程 你 要 做 很 多 事 。 


而 Vert.x 不 同 。 不 是 单 事 件 循 环 ， 每 个 Vertx 实例 都 维护 若干 个 事件 循环 。 默 认 情 况 下 ， 我 们 
选择 数量 基于 在 机 器 上 可 用 的 内 核 数 ， 但 可 以 自己 设置 。 


与 Node.js 不 同 是 Vertx 进 程 是 可 配置 的 ， 与 Node.js 不 同 
我 们 称 这 种 模式 多 反应 器 (Multi-Reactor) 模式 ， 以 区 别 于 单线 程 的 反应 器 模式 。 


注意 : 即使 Vertx 实例 维护 多 个 事件 循环 ， 任 何 特定 的 处 理 程序 将 永远 不 会 被 同时 执行 ， 在 大 
多 数 情况 下 (除了 worker verticles) 将 始终 使 用 完全 相同 的 事件 循环 调用 。 
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黄金 法 则 一 不 要 阻 蚂 事件 循环 


我 们 已 经 知道 Vert.x Api 是 非 阻 塞 ， 并 且 不 会 堵塞 事件 循环 。 如 果 你 堵塞 事件 循环 ， 那 事件 
循环 将 不 能 做 别 的 事 ， 因 为 它 被 阻塞 了 。 如 果 所 有 的 event loop 被 阻塞 了 ， 应 用 程序 将 完全 停 
ab! 


所 以 不 要 这 样 做 ! 你 已 经 被 警告 。 
阻塞 的 例子 包括 : 


e Thread.sleep() 

e 等 待 锁 

e 等 待 互 斥 体 或 监视 器 (例如 同步 段 ) 

e. 做 一 个 长 时 间 的 数据 库 操 作 和 等 待 返回 
e 做 复杂 的 计算 ， 需 要 很 长 的 时 间 。 

e 死 循环 。 


如 果 有 上 述 情况 停止 了 事件 循环 (event loop) ， 需 要 相当 长 的 时 间 ， 你 应 经 立即 去 下 一 步 ， 
并 等 待 进一步 的 指示 。 


这 个 时 间 具 体 多 长 ? 
具体 多 长 时 间 ? 它 取决 于 应 用 程序 需要 的 并 发 量 。 


如 果 你 有 一 个 单一 的 事件 循环 ， 并 且 你 想 要 处 理 每 秒 10000 的 http 请 求 ， 然 后 很 明显 ， 每 个 
请 求 不 能 超过 0.1 ms 要 处 理 ， 所 以 你 不 能 阻塞 比 这 更 多 的 时 间 。 


这 道 数学 题 并 不 是 困难 ， 作 为 练习 留 给 读者 。 


如 果 您 的 应 用 程序 不 响应 ， 可 能 你 阻塞 的 事件 循环 的 地 方 。 为 了 帮助 您 诊断 此 类 问题 ， 如 果 
它 检测 到 一 段 时 间 后 事件 循环 还 没有 恢复 ，Vert.X 会 自动 记录 警告 。 如 果 你 在 日 志 中 看 到 这 样 
的 警告 ， 那 么 你 就 应 该 去 检查 应 用 。 


Thread vertx-eventloop-thread-3 has been blocked for 20458 ms 


Vert.x 还 将 提供 堆栈 跟踪 来 确定 阻塞 发 生 的 位 置 。 
如 果 你 想 关 闭 这 些 警告 或 更 改 设置 ， 你 可 以 在 创建 Vertx 对 象 之 前 ， 使 用 VertxOptions 配 置 。 
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黄金 法 则 一 不 要 阻塞 事件 循环 
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在 完美 的 世界 ， 将 没有 战争 或 饥饿 ， 所 有 Api 将 使 用 异步 写 ， 阳 光明 媚 ， 绿 色 的 草地 有 跳 来 
跳 去 的 兔子 和 手 牵手 的 小 羊 羡 。 


但 是 ， 现 实 世 界 并 不 是 这 样 。( 你 看 过 新 闻 最 近 四 ?) 


ROW A due ru 
很 好 的 例子 是 JDBC API - 这 是 本 质 上 的 同步 ， 不 管 如 何 努力 尝试 ，Vert.x AT 8848 E EAR 
同步 。 


我 们 不 打算 在 一 夜 之 间 把 一 切 改写 成 异步 ， 所 以 我 们 需要 给 你 提供 一 个 方法 ， 一 个 Vert.X 应 用 
中 安全 地 使 用 "传统 ”的 阻塞 API 的 方法 。 


如 前 所 述 ， 直 接 在 事件 循环 里 调用 阻塞 操作 ， 会 妨碍 它 做 任何 其 他 有 用 的 工作 。 所 以 你 怎么 
能 这 样 呢 ? 


它 是 通过 调用 executeBlocking 指定 要 执行 的 阻塞 的 代码 和 在 执行 阻塞 的 代码 时 调用 返回 异步 
结果 处 理 程序 。 


过 调用 executeblocking ， 执 行 阻塞 代码 ， 当 阻塞 代码 执行 完成 后 通过 异步 回调 的 方式 返回 


vertx.executeBlocking(future -> { 
// Call some blocking API that takes a significant amount of time to return 
String result = someAPI.blockingMethod("hello"); 
future.complete(result); 
}, res -> { 
System.out.println("The result is: " + res.result()); 


}); 


默认 情况 下 ， 如 果 executeBlocking 从 相同 的 上 下 文 (例如 同一 垂直 实例 ) 调用 几 次 不 同 的 
executeBlocking 则 以 串 行 方式 执行 ( 即 一 个 接 一 个 ) 。 


默认 情况 下 ， 如 果 executeBlocking 在 同一 环境 (例如 同一 个 verticle 实 例 ) 多 次 调用 ， 那 么 不 
同 的 executeBlocking 将 串 行 执行 ( 即 一 个 接 一 个 ) 。 


如 果 不 关 系 执行 顺序 ， 调 用 executeBlocking 时 可 以 制定 ordered 参数 为 false 。 在 这 种 情况 
下 executeBlocking 会 与 Worker pool 并 行 执 行 。 


运行 阻塞 的 代码 替代 方法 是 使 用 worker verticle 
worker verticle 始 终 在 worker 池 中 的 线程 执行 
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Verticles 

Vert.x 带 有 一 个 简单 、 可 扩展 ，actor-like 开 箱 即 用 ， 你 可 以 用 来 节省 您 编写 您 自己 的 部 署 和 
并 发 模型 。 

此 模型 是 完全 可 选 的 , 如 果 你 不 想 去 用 ，Vert.x 不 会 强制 您 以 这 种 方式 创建 应 用 程序 。 


该 模型 并 不 要 求 是 一 个 严格 的 actor-model 的 实现 ， 但 它 确实 有 相似 之 处 ， 特 别 是 对 并 发 性 ， 
扩展 和 部 署 。 


若 要 使 用 此 模型 ， 把 代码 设置 为 verticles. 


Verticles 是 代码 的 得 到 部 署 和 运行 的 Vert.x 块 。Verticles 可 以 使 用 任何 Vert.x 支持 的 语言 编 
写 ， 单 个 应 用 程序 包含 verticles ， 可 以 使 用 多 种 语言 编写 。 


你 可 能 会 想 ，verticle 有 点 像 Actor Model 中 的 actor。 


应 用 通常 是 同一 个 Vert.x 实例 ， 同 时 由 多 个 verticle 实 例 组 成 。 不 同 的 verticle 实 例 通 过 event 
bus 发 送 消息 。 
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编写 Merticles 


Verticle 类 必须 实现 Verticle 接 口 。 
如 果 喜 欢 可 以 直接 实现 Verticle 接 口 ， 但 是 通常 简 答 的 方法 是 继承 抽象 类 AbstractVerticle 


下 面 是 Verticles 示 例 : 


public class MyVerticle extends AbstractVerticle { 


// Called when verticle is deployed 
public void start() { 
H 


// Optional - called when verticle is undeployed 
public void stop() { 
} 


通常 你 会 像 在 上 面 的 示例 一 样 重 写 start 方法 。 
当 Vert.x 部 署 verticle 后 ， 会 调用 start 方法 ， 当 调用 completed 后 ， 说 明 verticle 局 动 完 毕 。 
您 也 可 以 选择 可 以 履 盖 stop 方法 o 取消 部 署 的 时 候 会 调用 
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异步 Verticle 启 动 和 停止 


实现 异步 启动 


下 面 是 一 个 示例 : 


public class MyVerticle extends AbstractVerticle { 


public void start(Future«Void» startFuture) { 
// Now deploy some other verticle: 


vertx.deployVerticle("com.foo.OtherVerticle", res -» ( 
if (res.succeeded()) { 
startFuture.complete(); 
} else { 
startFuture.fail(); 


3) 


同样 地 ， 也 是 stop 方法 也 是 异步 。 如 果 你 想 要 做 一 些 verticle 的 清理 工作 ， 这 需要 一 


则 如 此 使 用 。 


public class MyVerticle extends AbstractVerticle { 


public void start() { 
// Do something 


public void stop(Future«Void» stopFuture) { 
obj.doSomethingThatTakesTime(res -> { 
if (res.succeeded()) { 
stopFuture.complete(); 
} else { 
stopFuture.fail(); 


3); 


此 


时 间 ， 


信息 : 你 不 需要 在 启动 一 个 verticle 后 手动 取消 部 署 子 verticles， 在 Verticle 的 stop 方法 。 当 父 


verticle’s 取 消 部 署 时 ，Vert.x 将 自动 取消 部 署 任何 子 verticles ° 
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Verticle 2: 7? 


有 三 种 不 同类 型 的 verticles: 

标准 Verticles 

这 些 都 是 最 常见 和 最 有 用 的 类 型 一 一 他 们 总 是 使 用 事件 循环 线程 执行 。 更 多 讨论 在 下 一 节 
Worker Verticles 


一 个 实例 是 永远 不 会 有 多 个 线程 并 发 执行 


多 线程 的 worker verticles 


一 个 实例 可 以 由 多 个 线程 同时 执行 。 


标准 verticles 


标准 verticles 当 创建 和 调用 start 方 法 时 分 配 一 个 event loop。 调 用 执行 都 在 相同 的 event loop 
Ee 


这 意味 着 我 们 可 以 保证 您 的 verticles 实 例 中 的 所 有 代码 总 是 都 执行 相同 的 事件 循环 上 (只 要 你 
不 调用 它 自己 创建 的 线程 0)。 

意味 着 可 以 在 程序 里 作为 单线 程 编写 所 有 的 代码 ， 把 担心 线程 和 扩展 的 问题 交 给 Vert.x。 没 
令 人 担忧 的 同步 和 更 多 不 稳定 的 问题 ， 也 避免 了 多 线程 死 锁 的 问题 。 


Worker verticles 


Worker verticles 就 像 标 准 的 verticles 一 样 ， 但 不 使 用 事件 循环 执行 ， 从 Vert.x worker 线 程 池 使 
用 一 个 线程 。 


worker verticles 专 为 调用 阻塞 的 代码 ， 因 为 他 们 不 会 阻止 任何 事件 循环 。 


如 果 你 不 想 使 用 worker verticles 运 行 阻塞 的 代码 ， 可 以 在 事件 循环 上 直接 运行 内 联 阻塞 代 
码 。 


如 果 您 要 以 worker verticles 的 方式 部 署 verticle， 需 要 调用 setWorker. 


DeploymentOptions options = new DeploymentOptions().setWorker(true); 
vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle", options); 


Worker verticle 实 例 永 远 不 会 有 多 个 线程 并 发 执行 ， 但 可 以 在 不 同 的 时 间 由 不 同 的 线程 执行 。 


多 线程 Worker verticles 

多 线程 的 worker verticle 就 像 正 常 worker verticle， 但 它 是 可 以 由 不 同 的 线程 同时 执行 。 

警告 | 多 线程 的 worker verticle 是 一 项 高 级 的 功能 ， 大 多 数 应 用 程序 会 对 他 们 来 说 没有 必 

要 。 因 为 在 这 些 verticles 并 发 ， 你 必须 非常 小 心 ， 使 用 标准 的 Java 技术 的 多 线程 编程 ， 以 保 
H vertice- £X A ° 
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`~ b da 3 hd 3 " 
VAR TE 7r AFRA verticles 
使 用 deployVerticle 方 法 部 署 verticles， 指 定 verticles 名 ， 也 可 以 把 已 经 创建 的 verticles 实 例 传 
注意 ! 部 署 verticles 实 例 只 是 Java » 


Verticle myVerticle = new MyVerticle(); 
vertx.deployVerticle(myVerticle); 
您 还 可 以 通过 指定 verticles 名 称 部 署 verticles. 
verticles 名 称 用 于 查找 特定 的 VerticleFactory ， 将 用 来 实例 化 实际 verticles 实 例 。 


不 同 verticle 工 厂 可 用 于 实例 化 不 同 语言 verticles 和 其 他 各 种 原因 ， 例 如 装载 服务 和 从 Maven 
在 运行 时 得 到 verticles。 


这 允许 您 从 Vert.x 支持 的 任何 语言 编写 的 其 他 语言 verticles 部 署 。 


这 里 是 verticles 的 部 署 一 些 不 同类 型 的 示例 : 


vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle"); 


// Deploy a JavaScript verticle 
vertx.deployVerticle("verticles/myverticle.js"); 


// Deploy a Ruby verticle verticle 


vertx.deployVerticle("verticles/my verticle.rb"); 
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verticle 名 称 映 射 到 一 个 verticle 工 厂 的 规则 


当 部 署 verticle(s) 使 用 一 个 名 称 ， 该 名 称 用 于 选择 将 实例 化 verticle(s) 的 实际 verticle 工 厂 。 


verticle 的 名 称 可 以 有 前 级 - 它 是 一 个 字符 串 , 后 跟 一 个 冒号 ， 它 如 果 存 在 ， 则 会 被 用 来 查找 工 
厂 ， 如 


js:foo.js // Use the JavaScript verticle factory 
groovy:com.mycompany.SomeGroovyCompiledVerticle // Use the Groovy verticle factory 
service:com.mycompany:myorderservice // Uses the service verticle factory 


如 果 没 有 前 级 ， 则 Vert.x 将 寻找 一 个 后 组 和 使 用 ， 例 如 查找 工厂 ， 


foo.js // Will also use the JavaScript verticle factory 
SomeScript.groovy // Will use the Groovy verticle factory 


如 果 没 有 前 级 或 后 级 ， 则 Vert.x 会 假设 它 是 Java 完整 类 名 称 (FQCN)， 然 后 实例 化 。 
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怎么 样 找到 Verticle Factories? 


大 多 数 的 Verticle factories 在 Vert.x 启动 时 从 类 路 径 中 加 载 并 注册 。 

你 可 以 通过 编程 方式 注册 和 注销 Verticle factories， 使 用 registerVerticleFactory 和 
unregisterVerticleFactory ° 
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等 待 部 署 完成 


可 能 部 署 完成 后 才 返 回 。 


-> 


Verticle 部 署 是 异步 的 


如 果 你 想 要 部 署 完成 后 通知 ， 您 可 以 部 署 指定 完成 处 理 程序 : 


vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle", res -> ( 


if (res.succeeded()) { 


System.out.println("Deployment id is: " + res.result()); 
) else { 
System.out.println("Deployment failed!"); 
} 
}); 


如 果 部 署 成 功 ， 该 完成 包含 部 署 ID 字符 串 的 结果 传递 给 处 理 程序 。 
如 果 你 想 要 取消 部 署 ， 可 以 稍 后 使 用 此 部 署 ID 。 
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取消 verticle 部 署 


部 署 可 以 通过 undeploy 取 消 部 署 . 


取消 部 署 本 身 是 异步 的 ， 所 以 如 果 想 要 在 取消 部 署 完 成 后 通知 ， 您 可 以 部 署 指定 完成 处 理 程 
序 : 


vertx.undeploy(deploymentID, res -> { 
if (res.succeeded()) { 
System.out.println("Undeployed ok"); 
) else { 
System.out.println("Undeploy failed!"); 
} 
}); 
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也 -* " 3 X 
18 € verticle 3: 7| Z& 
在 部 署 时 verticle 使 用 verticle 的 名 称 ， 可 以 指定 您 要 部 署 的 verticle 实 例 的 数目 : 


DeploymentOptions options = new DeploymentOptions().setInstances(16); 
vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle", options); 


用 于 跨 多 个 内 核 轻松 扩展 。 例 如 ， 您 可 能 有 web 服务 器 verticle 部 署 ， 服 务 器 是 多 核 的 ， 你 想 
要 部 署 多 个 实例 来 充分 利用 所 有 核心 。 
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配置 Verticle 


在 部 署 的 时 可 以 传递 一 个 JSON 形 式 的 配置 给 verticle : 


JsonObject config = new JsonObject().put("name", "tim").put("directory", "/blah"); 
DeploymentOptions options - new DeploymentOptions().setConfig(config); 
vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle", options); 


这 种 配置 可 通过 Context 对 象 获得 或 直接 使 用 config 方 法 。 


作为 一 个 JSON 对 象 返 回 的 配置 ， 您 可 以 检索 数据 ， 如 下 所 示 : 


System.out.println("Configuration: " + config().getString("name")); 
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在 Verticle 里 访问 环境 变量 。 
使 用 Java API 访问 环境 变量 和 系统 属性 : 


System.getProperty("prop"); 
System.getenv("HOME"); 
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Verticle fA A Z8 
默认 情况 下 ，Vert.x 具有 flat classpath » P? > 3$ Vert.x 部 署 verticles 使 用 当前 类 加 载 器 - 它 不 
会 创建 一 个 新 。 在 大 多 数 情况 下 这 是 最 简单 、 最 明确 和 理智 的 事情 。 


然而 ， 在 某 些 情况 下 ， 您 可 能 想 要 部 署 verticle， 所 以 在 您 的 应 用 程序 verticle 的 类 是 孤立 于 其 
他 。 

能 并 非 如 此 ， 例 如 ， 如 果 您 要 部 署 两 个 不 同 版 本 的 同一 个 Vert.x 实例 ， 类 名 相同 的 
verticle 或 如 果 你 有 两 个 不 同 的 verticles， 使 用 不 同 版 本 的 相同 的 jar Æ e 
隔离 组 ， 使 用 setisolatedclasses - 条 目 名 称 可 以 是 完整 类 名 > 
如 com. mycompany.myproject.engine.myclass 或 它 可 以 是 一 个 通配符 ， 将 匹配 任何 包 中 的 类 和 
任何 子 的 软件 包 ， 例 如 com.mycompany.myproject.* 将 匹配 com.mycompany.myproject 包 中 的 任 
何 类 或 任何 子 包 


请 注意 ， 只 有 【匹配 的 将 隔离 — 任何 其 他 类 将 由 当前 的 类 加 载 器 加 载 。 


也 可 以 与 setExtraClasspath 提 供 附 加 的 类 路 径 条 目 ， 所 以 如 果 你 想 要 加 载 的 类 或 资源 ， 已 经 
不 是 目前 的 主要 的 类 路 径 上 你 可 以 添加 这 。 


如 果 你 想 加 载 尚 不 存在 的 主要 类 路 径 类 或 资源 ， 你 可 以 使 用 setExtraClasspath 
警告 /说 惯 使 用 此 功能 。 类 加 载 程序 是 一 钒 蠕虫 ， 增 加 调试 困难 ， 除 其 他 事项 外 。 


这 里 是 一 个 使 用 隔离 组 隔离 verticle deployment 的 示例 。 


DeploymentOptions options = new DeploymentOptions().setIsolationGroup("mygroup"); 

options.setIsolatedClasses(Arrays.asList("com.mycompany.myverticle.*", 
"com.mycompany.somepkg.SomeClass", "org.somelibrary.*")); 

vertx.deployVerticle("com.mycompany.myverticle.VerticleClass", options); 
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高 可 用 性 (High Availability ) 
高 可 用 性 (HA) 可 以 在 Verticles deployed 时 启动 ， 当 vert.x 的 实例 突然 死 了 ， 从 集群 重新 部 署 
另外 的 vert.x 实例 。 


若 要 启用 高 可 用 性 运行 verticle， 只 是 追加 -ha JF X: 


vertx run my-verticle.js -ha 


当局 用 高 可 用 性 2 无 需 添加 -cluster ° 

有 关 高 可 用 性 功能 和 配置 的 高 可 用 性 和 故障 转移 (High Availability and Fail-Over) 部 分 ， 有 
更 多 细节 。 
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从 命令 行 运行 Verticles 


使 用 Vert.x ， 通 常 可 以 直接 在 Maven 或 Gradle 项 目 中 添加 Vert.x core 库 依 赖 。 
还 可 以 直接 从 命令 行 运行 Vert.x verticles ° 


做 到 这 一 点 ， 你 需要 下 载 和 安装 一 个 Vert.x ， 并 将 安装 的 bin 目录 添加 到 PATH 环境 变量 。 
还 要 确保 PATH 有 Java 8 JDK . 


注意 1JDK 是 需要 支持 的 Java 代 码 的 即时 编译 。 


现在 可 以 通过 使 用 vertx run 命令 运行 verticles。 这 里 有 一 些 例 子 : 


# Run a JavaScript verticle 
vertx run my verticle.js 


# Run a Ruby verticle 
vertx run a n other verticle.rb 


# Run a Groovy script verticle, clustered 
vertx run FooVerticle.groovy -cluster 


你 其 至 可 以 不 编译 直接 运行 Java 源 代码 ! 


vertx run SomeJavaSourceFile. java 


Vert.x 在 运行 之 前 会 先 编译 Java 源 文件 。 这 可 以 快速 原型 开发 verticles， 不 需要 设置 Maven 
或 Gradle ! 


更 多 信息 ， 请 在 命令 行 上 执行 vertx ° 
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Vert.x 退出 


由 Vert.x 实例 维护 的 线程 不 是 守护 程序 线程 ， 从 而 防止 JVM 退出 。 
如 果 你 就 入 Vert.x 和 你 已 完成 了 ， 你 可 以 调用 close 来 关闭 它 。 
这 将 关闭 所 有 的 内 部 线程 池 和 关闭 其 他 的 资源 ， 让 JVM 退出 。 
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Context ^i £ 


当 Vert.x 提 供 一 个 事件 的 处 理 程序 或 调用 Verticle 的 开始 或 停止 的 方法 ， 执 行 与 Context 相关 
联 。 一 般 Context 是 event-loop context 绑 定 特定 的 事件 循环 线程 。 因 此 ， 对 于 这 方面 的 执行 总 
是 发 生 在 该 完全 相同 的 事件 循环 线程 。 在 worker verticles 和 运行 内 瞩 阻 止 代码 worker context 
的 情况 下 将 使 用 一 个 线程 从 worker 线 程 池 的 执行 关联 。 


m 


要 获得 context， 请 使 用 getOrCreateContext 方 法 : 


Context context = vertx.getOrCreateContext(); 


如 果 当 前 线程 具有 一 个 与 它 相 关联 的 context， 它 重复 使 用 context 对 象 。 如 果 不 创 建新 实例 的 
context。 您 可 以 测试 您 取得 的 context 的 类 型 : 


Context context = vertx.getOrCreateContext(); 
if (context.isEventLoopContext()) { 
System.out.println("Context attached to Event Loop"); 


else if (context.isWorkerContext()) { 

System.out.println("Context attached to Worker Thread"); 

else if (context.isMultiThreadedWorkerContext()) 1 

System.out.println("Context attached to Worker Thread - multi threaded worker"); 
else if (! Context.isOnVertxThread()) { 

System.out.println("Context not attached to a thread managed by vert.x"); 


当 您 取得 context 对 象 时 ， 您 可 以 以 异步 方式 在 此 context 中 运行 代码 。 换 名 话说 ， 您 提交 相同 
的 context， 但 后 来 将 最 终 运行 任务 : 


vertx.getOrCreateContext().runOnContext( (v) -> { 
System.out.println("This will be executed asynchronously in the same context"); 


3) 


当 几 个 处 理 程序 在 相同 的 context 中 运行 时 ， 他 们 可 能 想 要 分 享 数 据 。context 对 象 提 供 方 法 来 
存储 和 获取 在 context 中 共享 的 数据 。 例 如 ， 它 可 以 让 你 通过 一 些 行动 runOnContext 运 行 数 
据 : 


final Context context = vertx.getOrCreateContext(); 
context.put("data", "hello"); 
context.runOnContext((v) -> { 

String hello = context.get("data"); 


3); 


context 对 象 还 可 让 您 使 用 的 config 方 法 访问 verticle 配 置 。 
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执行 定期 和 延迟 的 操作 


在 Vert.x 中 执行 定期 和 延迟 的 操作 是 非常 常见 的 。 


o 


在 标准 verticles 中 ， 不 能 使 用 thread sleep 引入 延迟 ， 这 样 会 止 事件 循环 线程 
相反 ， 您 可 以 使 用 Vert.x 计时 器 。 定 时 器 可 以 一 次 性 的 计时 器 或 定期 的 计时 器 。 我 们 将 讨论 
两 个 
一 次 性 的 计时 器 
一 个 单 次 定时 器 有 一 定 的 延迟 之 后 调用 一 个 事件 处 理 程序 ， 以 毫秒 为 单位 表示 。 

时 


aa 
s ^ 


使 用 setTimeout 方 法 启动 计 


long timerID = vertx.setTimer(1000, id -> { 
System.out.println("And one second later this is printed"); 


3) 


System.out.println("First this is printed"); 


e 
LE 
Paw 
Er 
a 
o 


返回 值 是 一 个 唯一 的 定时 器 id， 以 后 可 用 于 取消 计时 器 。 该 处 理 器 还 通过 什 
定期 计时 器 

您 还 可 以 设置 一 个 计时 器 来 定期 启动 ， 通 过 使 用 setPeriodic 方 法 。 

会 有 一 个 初始 延迟 等 于 周期 。 

setPeriodic 的 返回 值 是 一 个 唯一 的 计时 器 的 id (long)。 如 果 以 后 计时 器 需要 取消 ， 可 以 使 用 
id ° 

传递 到 计时 器 事件 处 理 程序 的 参数 也 是 唯一 的 计时 器 的 id: 


请 记 住 ， 计 时 器 会 定期 触发 。 如 果 你 的 周期 性 处 理 需要 相当 长 的 时 间 进 行 ， 你 的 计时 器 事件 
可 以 运行 连续 或 更 糟 的 是 : 堆积 。 


在 这 种 情况 下 ， 您 应 该 考虑 使 用 setTimer 替 代 。 一 旦 您 处 理 已 完成 ， 您 可 以 设置 下 一 个 计时 
Xe. 


long timerID = vertx.setPeriodic(1000, id -> { 
System.out.println("And every second this is printed"); 


3): 


System.out.println("First this is printed"); 


取消 计时 器 
若 要 取消 一 个 定期 的 计时 器 ， 请 调用 cancelTimer 指 定 的 计时 器 的 id。 例如 : 


vertx.cancelTimer(timerID); 
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Verticles 自动 清理 


如 果 您 正在 从 verticles 内 创建 的 计时 器 ， 这 些 计时 器 将 被 自动 关闭 verticle undeployed ° 
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事件 总 线 (Event Bus) 


event bus 是 Vert.x 的 中 枢 神 经 系统 。 


通过 Vert.x 实 例 使 用 eventBus 方 法 得 到 单一 的 event bus 实 例 。 事件 总 线 允 许 您 的 应 用 程序 相 
互 沟通 ， 不 论 何 种 语言 ， 他 们 写 的 以 及 他 们 是 否 在 同一 个 Vert.x 实例 ， 或 在 一 个 不 同 的 
Vert.x 实例 的 不 同 部 分 


它 基 至 可 以 弥合 ， 允 许 客户 端 JavaScript 运行 在 浏览 器 上 相同 的 事件 总 线 进 行 通信 。 


事件 总 线 构成 了 一 个 分 布 式 对 等 消息 传递 系统 跨越 多 个 服务 器 节点 和 多 个 浏览 器 。 
事件 总 线 支持 发 布 /订阅 ， 点 到 点 和 请 求 -响应 消息 。 


事件 总 线 API 是 非常 简单 的 。 它 基本 上 涉及 注册 处 理 程序 ， 注 销 处 理 程序 和 发 送 和 发 布 消 


第 一 次 一 些 理论 : 
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理论 


处 理 
事件 到 地 址 总 线 上 发 送 邮 件 . 


Vert.x 并 不 费心 处 理 计划 任何 幻想 。 在 Vert.x 的 地 址 是 只 是 一 个 字符 串 。 任 何 字符 串 是 有 效 
的 。 然 而 它 是 计划 的 明智 地 使 用 某 种 类 型 ， 例 如 使 用 句点 划 定 一 个 命名 空间 。 


一 些 例子 的 有 效 地 址 是 europe.news.feed1 ^ acme.games.pacman ^ 香肠 和 XX。 
处 理 程序 

在 处 理 程序 接收 消息 。 你 注册 一 个 处 理 程序 的 地 址 。 

很 多 不 同 的 处 理 程序 可 以 注册 在 相同 的 地 址 。 

单个 处 理 程序 可 以 注册 在 许多 不 同 的 地 址 。 

发 布 /订阅 消息 传递 

事件 总 线 支 持 发 布 消息 。 

消息 发 布 到 的 地 址 。 发 布 是 指 信息 传递 给 所 有 处 理 程序 ， 注 册 在 该 地 址 。 

这 是 熟悉 的 发 布 订阅 消息 传递 模式 。 

点 到 点 和 请 求 -响应 消息 

事件 总 线 还 支持 点 到 点 消息 传递 。 

邮件 发 送 到 某 个 地 址 。Vert.x 然后 将 传送 到 位 于 该 地 址 注册 的 处 理 程 序 之 一 。 
如 果 有 多 个 处 理 程序 ， 登 记 的 地 址 ， 将 选择 一 个 使 用 非 严格 -轮转 调度 算法 。 
使 用 点 到 点 消息 传递 ， 发 送 消息 时 ， 可 以 指定 一 个 可 选 的 答复 处 理 程序 。 


当 消息 由 收 件 人 收 到 ， 并 且 已 被 处 理 时 ， 收 件 人 可 以 选择 决定 对 消息 进行 回复 。 如 果 他 们 这 
样 做 答复 处 理 程序 将 被 调用 。 


当 回 到 在 发 件 人 收 到 的 答复 时 ， 它 也 可 以 被 回复 。 这 可 以 是 重复 的 广告 -无 穷尽 ， 并 允许 一 个 
对 话 框 ， 可 以 设置 两 个 不 同 的 verticles 之 间 。 


这 是 一 种 常见 的 消息 传递 模式 ， 称 为 请 求 -响应 模式 。 


尽 最 大 努力 交付 


Vertx 最 好 来 传递 邮件 ， 并 不 会 有 意识 地 把 它们 扔 掉 。 这 就 被 所 谓 尽 最 大 努力 交付 。 
然而 ， 万 一 失败 的 全 部 或 部 分 的 事件 总 线 ， 有 可 能 性 消息 将 丢失 。 


如 果 您 的 应 用 程序 关心 丢失 的 邮件 ， 你 应 该 代码 您 的 处 理 程序 是 等 需 的 和 你 发 件 人 可 以 在 恢 
复 后 重 试 。 


类 型 的 消息 
开 箱 即 用 Vert.x 允许 任何 原始 /简单 类 型 、 字符 串 或 buffers 将 作为 邮件 发 送 。 
然而 它 是 公约 和 惯例 在 Vert.x 以 json 格式 发 送 邮 件 


JSON 是 很 容易 创建 、 读 取 和 解析 在 Vert.x 支持 ， 因 此 它 已 成 为 一 种 通用 语言 为 Vert.x 的 所 
有 语言 。 


然而 你 不 被 迫使 用 JSON， 如 果 你 不 想 去 。 
事件 总 线 是 非常 灵活 ， 也 支持 通过 事件 总 线 发 送 任意 对 象 。 你 这 样 做 是 通过 定义 您 想 要 发 送 
的 对 象 的 codec 。 
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事件 总 线 API 
让 我 们 跳 进 API 


获取 事件 总 线 
你 获取 到 事件 总 线 的 引用 ， 如 下 所 示 : 


EventBus eb = vertx.eventBus(); 


还 有 每 个 Vert.x 实例 事件 总 线 的 单个 实例 。 


注册 处 理 程 序 


最 简单 的 方法 来 注册 一 个 处 理 程序 用 consumer。 下 面 是 一 个 示例 : 


EventBus eb = vertx.eventBus(); 


eb.consumer("news.uk.sport", message -> { 
System.out.println("I have received a message: " + message.body()); 


3); 


当 邮 件 到 达 您 的 处 理 程序 时 ， 将 调用 您 的 处 理 程序 ， 在 message 中 传递 . 

从 对 consumer() 的 调用 返回 的 对 象 是 一 个 实例 MessageConsumer 随后 ， 此 对 象 可 以 用 于 注 
销 处 理 程序 中 ， 或 使 用 处 理 程序 以 流 的 形式 。 

或 者 你 可 以 使 用 consumer 对 返回 MessageConsumer 与 没有 处 理 程序 设置 ， 然 后 在 那 设置 处 
理 程序 。 例 如 : 


EventBus eb = vertx.eventBus(); 


MessageConsumer«String» consumer - eb.consumer("news.uk.sport"); 


consumer.handler(message -> { 
System.out.println("I have received a message: " + message.body()); 


3); 


注册 时 聚集 的 事件 总 线 上 的 一 个 处 理 程序 ， 它 可 以 有 一 些 时 间 为 要 达到 该 群集 的 所 有 节点 的 
登记 。 


如 果 你 想 要 这 已 完成 时 通知 ， 您 可 以 注册 的 MessageConsumer 3t % completion handler ° 


consumer.completionHandler(res -> { 
if (res.succeeded()) { 
System.out.println("The handler registration has reached all nodes"); 
} else { 
System.out.println("Registration failed!"); 
} 
}); 


未 注册 的 处 理 程 序 
若 要 撤消 注册 的 处 理 程序 ， 调 用 unregister 


如 果 你 在 一 个 群集 事件 总 线 ， 未 登记 可 能 需要 一 些 时 间 来 传播 跨 节点 ， 如 果 你 想 要 这 完成 后 
通知 使 用 unregister 


consumer.unregister(res -> { 
if (res.succeeded()) { 
System.out.println("The handler un-registration has reached all nodes"); 
} else { 
System.out.println("Un-registration failed!"); 
} 
}); 
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` "^ 

发 布 ‘ 息 

发 布 一 条 消息 是 简单 的 。 只 需 使 用 publish 指 定 地 址 发 布 到 。 
eventBus.publish("news.uk.sport", "Yay! Someone kicked a ball"); 


那 消 息 然后 将 送 交 注册 的 反对 地 址 news.uk.sport 的 所 有 处 理 程序 。 
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发 送 消息 


发 送 一 条 消息 将 导致 只 有 一 个 Handlers 在 接收 该 消息 的 地 址 注册 。 这 是 点 对 点 的 消息 传递 模 
式 。 这 个 Handlers 的 选择 是 一 个 非 严 格 的 循环 方式 。 


发 送 一 条 消息 时 ， 可 以 send 


eventBus.send("news.uk.sport", "Yay! Someone kicked a ball"); 
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消息 设置 headers 


通过 event bus 发 送 的 消息 还 可 以 包含 头 文件 。 


这 可 以 通过 发 送 或 发 布 时 提供 DeliveryOptions 指 定 : 


DeliveryOptions options = new DeliveryOptions(); 
options.addHeader("some-header", "some-value"); 
eventBus.send("news.uk.sport", "Yay! Someone kicked a ball", options); 
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消息 顺序 


和 发 送 顺序 相同 。 
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消息 对 象 


在 消息 Handlers 中 接收 的 对 象 是 一 个 Message。 
该 消息 的 body 对 应 于 发 送 或 发 布 的 对 象 。 
消息 标 头 有 headers。 
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确认 消 AX iX d 


当 使 用 send event bus 尝试 将 消息 传递 到 event bus 中 注册 的 MessageConsumer 。 

在 某 些 情况 下 是 有 用 的 ， 发 送 者 知道 什么 时 候 ， 消 费 者 已 经 收 到 了 消息 和 "processing"。 
要 确认 该 消息 已 被 处 理 ， 消 费 者 可 以 通过 调用 reply 对 消息 进行 回复 。 

当 发 生 这 种 情况 时 ， 它 会 导致 一 个 回复 ， 发 送 回 发 送 端 和 应 答 处 理 程 序 被 调用 的 答复 。 
一 个 例子 可 以 说 明 这 一 


接收 : 


MessageConsumer<String> consumer = eventBus.consumer("news.uk.sport"); 


consumer.handler(message -> ( 


System.out.println("I have received a message: " + message.body()); 
message.reply("how interesting!"); 
15 


eventBus.send("news.uk.sport", "Yay! Someone kicked a ball across a patch of grass", a 


r -> { 
if (ar.succeeded()) { 
System.out.println("Received reply: " + ar.result().body()); 


J 
3): 


答 可 以 包含 一 个 消息 体 ， 它 包含 有 用 的 信息 。 


"processing" 实 际 上 指 的 是 应 用 程序 定义 和 完全 取决 于 在 什么 消息 上 消费 者 并 不 是 Vert.x 
event bus 本 身 知道 或 关心 的 东西 。 


一 些 例子 : 


e 一 个 简单 的 消息 消费 者 ， 它 实现 了 一 个 服务 ， 它 返回 的 时 间 是 一 天 中 的 时 间 ， 将 确认 一 
个 消息 ， 包 含 时 间 的 答复 正文 

e 如 果 消 息 被 成 功 地 保存 在 存储 中 ， 或 不 正确 的 话 ， 它 将 实现 一 个 持久 队列 的 消息 ， 如 果 
消息 被 成 功 地 保存 ， 可 能 会 对 其 进行 应 答 。 

e 如 果 消 息 成 功 处 理 ， 它 可 以 从 数据 库 中 删除 
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确认 消息 /发 送 答复 


50 


发 送 超时 

发 送 答复 处 理 消 息 时 你 可 以 在 DeliveryOptions 中 指定 超时 . 
如 果 在 该 时 间 内 没有 收 到 答复 ， 答 复 处 理 程序 将 调用 失败 。 
默认 的 超时 时 间 为 30 秒 。 
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发 送 失败 


消息 发 送 失败 有 其 他 原因 ， 包 括 : 


e 没有 可 用 来 向 其 发 送 消息 的 handlers 
e 收 件 人 已 明确 地 使 用 fail (失败 ) 的 消息 


在 所 有 情况 下 回复 处 理 程序 将 调用 具体 的 失败 。 
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消息 编 解 码 器 


如 果 你 定义 并 注册 了 一 个 message codec， 你 可 以 将 任何 对 象 发 送 到 event bus 上 ° 


消息 编 解 码 器 有 一 个 名 称 ， 您 在 发 送 或 发 布 该 消息 时 在 DeliveryOptions 中 指定 该 名 称 : 
eventBus.registerCodec(myCodec); 
DeliveryOptions options - new DeliveryOptions().setCodecName(myCodec.name()); 
eventBus.send("orders", new MyPOJO(), options); 

如 果 你 总 是 希望 使 用 相同 的 编 解 码 器 ， 用 于 特定 类 型 ， 那 么 你 可 以 注册 成 为 一 个 默认 编码 解 

码 器 ， 然 后 你 不 需要 对 每 个 发 送 的 传递 选项 中 指定 编码 解码 器 : 
eventBus.registerDefaultCodec(MyPOJO.class, myCodec); 


eventBus.send("orders", new MyPOJO()); 


注销 消息 编 解 码 器 使 用 unregisterCodec. 


消息 的 编码 解码 器 不 总 是 要 为 相同 的 类 型 进行 编码 和 解码 。 例 如 ， 您 可 以 编写 允许 发 送 ， 
MyPOJO 类 的 编 解码 器 ， 但 该 消息 发 送 到 一 个 处 理 程序 时 它 到 达 作为 一 个 MyOtherPOJO 


Xo 
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群集 Event Bus 


Event Bus 并 不 仅仅 存在 于 一 个 单一 的 Vert.x 实 例 。 通 过 网 络 上 的 不 同 集群 实例 Vert.x 一 起 就 可 
以 形成 一 个 单一 的 ， 分 布 式 的 ，Event Bus。 
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—€— EA 
集群 编程 
如 果 您 要 以 编程 方式 创建 您 的 Vert.x 实例 ， 通 过 将 Vert.x 实例 配置 获得 集群 的 event bus; 


VertxOptions options = new VertxOptions(); 
Vertx.clusteredVertx(options, res -> ( 
if (res.succeeded()) 1 
Vertx vertx - res.result(); 
EventBus eventBus - vertx.eventBus(); 


System.out.println("We now have a clustered event bus: " + eventBus); 
) else { 
System.out.println("Failed: " + res.cause()); 
} 
}); 


你 还 应 该 确保 你 已 经 在 你 的 类 路 径 中 实现 ClusterManager， 例 如 上 默认 
HazelcastClusterManager ° 
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命令 行 上 的 集群 


可 以 在 命令 行 中 运行 Vertx 集群 
vertx run my-verticle.js -cluster 
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自动 清理 Merticles 


如 果 你 从 verticles 里 注册 event bus 处 理 程序 ， 当 verticle 取 消 部 署 时 处 理 程序 将 被 自动 注销 。 
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JSON 


不 像 一 些 其 他 语言 ，Java 没 有 对 JSON 提 供 一 流 的 支持 ， 所 以 我 们 提供 了 两 个 类 ， 来 使 你 的 应 
用 程序 Vert.x 处 理 JSON 更 容易 一 点 。 

JSON 4 £ 

JsonObject 类 表示 JSON 51 & ° 


JSON 对 象 基 本 上 是 有 字符 囊 键 和 值 的 map， 值 可 以 是 JSON 的 一 个 支持 的 类 型 (字符 囊 ， 数 
字 ， 布 尔 值 ) 。 


JSON 对 象 还 支持 null 值 。 
创建 JSON 对 象 
可 以 使 用 默认 的 构造 函数 创建 空 的 JSON 对 象 。 


可 以 通过 JSON 格式 字符 串 创建 一 个 JSON 对 象 ， 如 下 所 示 : 


String jsonString = "{\"foo\":\"bar\"}"; 
JsonObject object = new JsonObject(jsonString); 
& H3 JSON 对 象 
使 用 put 方 法 将 值 放 入 的 JSON 对 象 。 


该 方法 可 以 链接 调用 ， 因 为 使 用 fluent API: 


JsonObject object = new JsonObject(); 
object.put("foo", "bar").put("num", 123).put("mybool", true); 


从 JSON 对 象 中 获取 值 
使 用 getXXX 方 法 从 JSON 对 象 中 获取 值 ， 例 如 : 


String val = jsonObject.getString("some-key"); 
int intVal - jsonObject.getInteger("some-other-key"); 


JSON 对 象 转换 为 字符 串 


使 用 encode 对 象 编码 为 一 个 字符 串 形式 。 


JSON 数组 

JsonArray X & 7 JSON 数组 。 

一 个 JSON 数组 是 一 个 序列 的 值 (字符 串 、 数字 、 布尔 值 )。 
JSON 数组 也 可 以 包含 空 值 。 

创建 JSON 数组 

可 以 使 用 默认 的 构造 函数 创建 空 的 JSON 数组 。 


可 以 通过 JSON 格式 字符 串 创建 一 个 JSON 数组 ， 如 下 所 示 : 


String jsonString = "[N"fooN", N"barN"]"; 
JsonArray array - new JsonArray(jsonString); 
添加 一 个 条 目 到 JSON 数组 


使 用 add 方 法 将 条 目 添 加 到 JSON 数组 。 


JsonArray array = new JsonArray(); 
array.add("foo").add(123).add(false); 


从 JSON 数组 中 获取 值 


使 用 getXXX 方 法 从 JSON 数组 中 获取 值 ， 例 如 : 


String val = array.getString(90); 
Integer intVal - array.getInteger(1); 
Boolean boolVal - array.getBoolean(2); 


JSON 数组 转换 为 字符 串 
使 用 encode 方 法 将 数组 编码 成 字符 串 形 式 。 
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缓冲 区 


大 多 数 数据 是 使 用 缓冲 区 抛 入 Vert.Xx 内 “。 


缓冲 区 是 零 个 或 多 个 字 节 ， 可 以 读 取 或 写 入 ， 并 自动 扩展 ， 以 适应 任何 字 节 写 入 它 。 你 或 许 
可 以 认为 缓冲 区 是 智能 字 节 数组 。 


创建 缓冲 区 

缓冲 区 可 以 通过 静态 的 Bufferbuffer 方 法 创建 。 

可 以 从 字符 串 或 字 节 数 组 ， 初 始 化 缓冲 区 ， 也 可 以 创建 空 缓冲 区 。 
下 面 是 创建 缓冲 区 的 一 些 示 例 : 


创建 一 个 新 的 空 缓冲 区 : 
Buffer buff = Buffer.buffer(); 
从 一 个 字符 串 创建 一 个 缓冲 区 。 字 符 串 将 在 缓冲 区 中 使 用 utf-8 编码 。 
Buffer buff = Buffer.buffer("some string"); 
从 字符 串 创 建 缓冲 区 : 该 字符 串 将 使 用 指定 的 编码 ， 例 如 
Buffer buff = Buffer.buffer("some string", "UTF-16"); 


从 byte[] 创 建 一 个 缓冲 区 。 


byte[] bytes = new byte[] (1, 3, 53; 
Buffer buff - Buffer.buffer(bytes); 


创建 一 个 初始 大 小 的 缓冲 区 。 如 果 你 知道 你 的 缓冲 区 将 有 一 定数 量 的 数据 写 入 ， 你 可 以 在 创 
建 缓冲 区 时 指定 缓冲 区 大 小 。 这 使 得 缓冲 最 初 分 配 多 的 内 存 ， 比 缓冲 区 自动 调整 多 次 作为 数 
据 写 入 它 更 有 效 。 


请 注意 ， 这 种 方法 创建 的 缓冲 区 是 空 的 。 它 不 能 创建 大 小 为 零 的 缓冲 。 


Buffer buff = Buffer.buffer(10000); 


写 入 缓冲 区 


有 两 种 方法 来 写 入 缓冲 区 : 添加 、 和 随机 存 取 。 在 任何 情况 下 ， 缓 冲 区 将 自动 扩展 ， 以 包括 
字 节 。 用 缓冲 区 获取 IndexOutOfBoundsException 这 是 不 可 能 的 。 


添加 到 缓冲 区 
要 添加 到 缓冲 区 ， 您 可 以 使 用 appendXXX 方 法 。 添 加 各 种 不 同类 型 存在 的 方法 。 


appendXXX 方 法 的 返回 值 是 缓冲 区 本 身 ， 以 便 这 些 可 以 将 链接 : 


Buffer buff = Buffer.buffer(); 
buff.appendInt(123).appendString("helloNn"); 


socket.write(buff); 


写 入 随机 存 取 缓 冲 区 


使 用 SetXXX 方 法 ， 在 特定 的 索引 中 ， 可 以 写 入 缓冲 区 中 。Set 的 方法 存在 各 种 不 同 的 数据 类 
型 。 所 有 的 设置 的 方法 取 索 引 作 为 第 一 个 参数 -这 代表 缓冲 区 中 的 位 置 从 哪里 开始 写 入 数据 。 


缓冲 区 将 总 是 需要 时 扩展 ， 以 容纳 数据 。 
Buffer buff = Buffer.buffer(); 


buff.setInt(1000, 123); 
buff.setString(0O, "hello"); 


从 缓冲 区 读 取 


使 用 getXXX 方 法 从 缓冲 区 读 取 数 据 。 获 得 方法 存在 不 同 的 数据 类 型 。 这 些 方法 的 第 一 个 参数 
是 获取 数据 的 缓冲 区 中 的 一 个 索引 。 


Buffer buff = Buffer.buffer(); 
for (int i = 0; i < buff.length(); i += 4) { 
System.out.println("int value at " + i + " is " + buff.getInt(i)); 


} 


使 用 无 符号 数字 


无 符号 的 数字 可 以 通过 getUnsignedXXX、appendUnsignedXXX 和 setUnsignedXXX 的 方法 
读 取 或 追加 / 套 到 缓冲 区 。 这 是 有 用 的 ， 当 实现 一 个 编 解 码 器 的 网 络 协议 优化 ， 以 尽量 减少 带 
3L 18 46 o 


在 以 下 示例 中 ，200 是 设置 在 指定 的 位 置 只 有 一 个 字 节 : 


Buffer buff = Buffer.buffer(128); 

int pos - 15; 

buff.setUnsignedByte(pos, (short) 200); 
System.out.println(buff.getUnsignedByte(pos)); 


控制 台 显 示 '200' ° 

缓冲 区 长 度 

使 用 length 来 获取 缓冲 区 的 长 度 。 缓 冲 区 的 长 度 是 在 缓冲 区 的 最 大 索引 + 1 字 节 的 索引 。 
复制 缓冲 区 

使 用 copy， 复 制 缓冲 区 


切片 的 缓冲 区 


切片 的 缓冲 区 是 一 个 新 的 缓冲 区 ， 背 对 着 原来 的 缓冲 区 ， 即 它 将 不 复制 的 基础 数据 。 使 
用 slice 创 建 切 片 的 缓冲 区 


缓冲 区 重新 使 用 
一 个 缓冲 区 写 入 套 接 字 或 其 它 类 似 的 地 方 之 后 ， 他 们 不 能 被 重新 使 用 。 
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编写 TCP 服务 器 和 客户 端 
Vert.x 可 以 轻松 地 编写 非 阻塞 的 TCP 客户 端 和 服务 器 。 
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编写 TCP JR 4-5 


创建 TCP 服务 器 
使 用 最 简单 的 方法 来 创建 一 个 TCP 服务 器 ， 使 用 所 有 默认 选项 如 下 所 示 : 


NetServer server = vertx.createNetServer(); 


配置 TCP 服务 器 
如 果 你 不 想 默 认 值 ， 可 以 将 服务 器 配置 通过 传 入 一 个 NetServerOptions 实 例 来 创建 它 : 


NetServerOptions options = new NetServerOptions().setPort(4321); 
NetServer server - vertx.createNetServer(options); 


启动 服务 器 监听 
使 用 listen 告 诉 服务 监听 传 入 的 请 求 
告诉 要 听 的 主机 和 端口 作为 选项 中 指定 的 服务 器 : 


需要 在 选项 ( Netserveroptions ) 中 指定 的 主机 和 端口 : 


NetServer server = vertx.createNetServer(); 
server.listen(); 


或 在 调用 listen 中 指定 的 主机 和 端口 ， 忽 略 Netserveroptions 配置 : 


NetServer server = vertx.createNetServer(); 
server.listen(1234, "localhost"); 


默认 主机 是 0.0.0.0 ， 意 味 着 ' 监 听 所 有 可 用 的 地 址 '， 上 默认 端口 是 0， 这 是 一 个 特殊 值 ， 告 诉 
服务 器 随机 找 一 个 未 使 用 的 本 地 端口 使 用 。 
监 实 的 绑 定 是 异步 的 ， 所 以 服务 器 可 能 不 会 实际 被 侦 听 ， 直 到 有 一 段 时 间 后 ， 调 用 返回 。 


如 果 想 要 listen 实 际 监听 后 通知 你 ， 可 以 提供 listen 调 用 处 理 程序 。 例 如 : 


NetServer server = vertx.createNetServer(); 
server.listen(1234, "localhost", res -> { 
if (res.succeeded()) 1 
System.out.println("Server is now listening!"); 
} else ( 
System.out.println("Failed to bind!"); 
} 
}); 


监听 随机 端口 
如 果 o 用 作 的 监听 端口 ， 则 服务 器 将 找到 一 个 未 使 用 的 随机 端口 监听 。 


若 要 找 出 服务 器 正在 监听 的 旨 正 端口 ， 您 可 以 调用 actualPort. 


NetServer server = vertx.createNetServer(); 
server.listen(0, "localhost", res -> ( 
if (res.succeeded()) { 


System.out.println("Server is now listening on actual port: " + server.actualPort( 
)); 
} else { 
System.out.println("Failed to bind!"); 
} 
}); 


若 要 连接 时 通知 您 需要 设置 connectHandler: 


NetServer server = vertx.createNetServer(); 
server.connectHandler(socket -> { 
// Handle the connection in here 
1; 
当 进 行 连接 时 的 处 理 程序 将 调用 Netsocket 实 例 。 
这 是 一 个 类 似 于 socket-like 的 接口 的 真实 连接 ， 并 且 人 允许 你 读 写 数据 以 及 做 其 他 各 种 类 似 的 事 
情 ， 比 如 关闭 套 接 字 。 


从 Socket 读 取 数 据 
从 socket 读 取 数 据 要 在 socket 上 设置 handler。 


每 次 在 socket 上 接收 到 数据 Buffer 实 例 ， 将 调用 此 处 理 程序 。 


NetServer server - vertx.createNetServer(); 
server.connectHandler(socket -> { 
socket.handler(buffer -> ( 
System.out.println("I received some bytes: " + buffer.length()); 
15; 
15 


数据 写 入 socket 
使 用 write 写 到 Socket. 


Buffer buffer = Buffer.buffer().appendFloat(12.34f).appendInt(123); 
socket.write(buffer); 


// Write a string in UTF-8 encoding 
socket.write("some data"); 


// Write a string using the specified encoding 
Ssocket.write("some data", "UTF-16"); 


» 


写 操作 是 异步 的 ， 调 用 返回 之 后 可 能 不 会 发 生 。 
关闭 的 处 理 程序 (handler) 


如 果 你 想 要 关闭 socket 时 得 到 通知 ， 可 以 设置 closeHandler : 


socket.closeHandler(v -> ( 
System.out.println("The socket has been closed"); 


}); 
处 理 异 常 


您 可 以 设置 exceptionHandler 接 收 socket 发 生 的 任何 异常 。 


Event bus 5 handler 


每 个 socket 自 动 注册 event bus 上 的 handler， 当 这 个 handler 接 收 到 任何 buffers 时 ， 它 会 将 它们 
写 入 到 本 身 。 


这 使 您 可 以 将 数据 写 到 socket， 它 可 能 是 在 完全 不 同 的 verticle 或 甚至 在 不 同 的 Vert.x 实例 ， 
通过 将 buffers 发 送 到 该 处 理 程序 的 地 址 。 


由 writeHandlerID 给 出 了 处 理 程序 的 地 址 


本 地 和 远程 地 址 
可 以 使 用 localAddress 检 索 NetSocket 的 本 地 地 址 ， 


可 以 使 用 remoteAddress 检 索 远 程 地 址 ( 即 地址 连接 的 另 一 端 ) 的 NetSocket. 


从 classpath 发 送 文件 或 资源 


直接 使 用 sendFile 就 可 以 将 文件 写 入 socket。 这 是 非常 有 效 的 发 送 文件 的 方法 ， 因 为 它 可 以 由 
操作 系统 内 核 直接 支持 。 


socket.sendFile("myfile.dat"); 


Streaming sockets 


NetSocket 的 实例 也 是 ReadStream 和 WriteStream 的 实例 ， 因 此 他 们 可 以 被 用 于 泵 送 数 据 ， 可 
以 从 其 他 的 读 和 写 streams » 


详细 信息 ， 请 参阅 Streams 章 。 


升级 到 SSL/TLS 连接 


非 ssL/TLS 连接 可 以 使 用 UpgradeToSsl 升 级 到 ssL/TLS ° 


服务 器 或 客户 端 必 须 配 置 为 ssL/TLS 才能 正常 工作 。 详 细 信 息 请 参阅 关于 ssL/TLS 章节 。 


关闭 一 个 TCP 服务 器 
叫 close 来 关闭 服务 器 。 关 闭 服务 器 关闭 任何 打开 的 连接 ， 并 释放 所 有 的 服务 器 资源 。 


关闭 是 异步 的 ， 可 能 无 法 立即 返回 。 如 果 你 想 要 关闭 已 完成 然后 通知 ， 可 以 通过 handler 做 
到 o 


当 关 闭 已 全 面 完 成 ， 然 后 将 调用 此 处 理 程序 。 


server.close(res -> { 
if (res.succeeded()) { 
System.out.println("Server is now closed"); 
) else { 
System.out.println("close failed"); 
} 
}); 


Verticles 自动 清理 


您 正在 从 verticles 内 创建 rcp 服务 器 和 客户 端 ，verticle 取消 部 署 时 这 些 服务 器 和 
Pul 


iz 4 


Scaling - sharing TCP JE 2- 2 
任何 TCP 服 务 器 的 处 理 吕 总 是 在 相同 的 事件 循环 线程 执行 。 

意味 着 ， 如 果 在 多 核 的 服务 器 上 运行 ， 而 你 只 部 署 一 个 实例 ， 那 么 最 多 使 用 一 个 核心 。 
为 了 利用 你 的 服务 器 更 多 的 核心 ， 你 将 需要 部 署 服务 器 的 多 个 实例 。 


您 可 以 以 编程 方式 在 代码 中 实例 化 多 个 实例 : 


for (int i = 0; i < 10; i++) { 
NetServer server = vertx.createNetServer(); 
server.connectHandler(socket -> { 
socket .handler (buffer -> { 
// Just echo back the data 
socket.write(buffer); 


3); 
3) 


server.listen(1234, "localhost"); 


} 


ii 


或 者 ， 如 果 您 正在 使 用 verticles 你 可 以 简单 地 通过 使 用 命令 行 选 项 -instances 部 署 服务 器 
verticle 的 多 个 实例 : 


vertx run com.mycompany.MyVerticle -instances 10 


或 以 编程 方式 部 署 verticle 


DeploymentOptions options = new DeploymentOptions().setInstances(10); 
vertx.deployVerticle("com.mycompany.MyVerticle", options); 


一 旦 你 这 样 做 ， 你 会 发 现 echo 服 务 器 的 功能 与 以 前 的 功能 相同 ， 但 可 以 利用 您 在 您 的 服务 器 
上 的 所 有 核心 ， 可 以 处 理 更 多 的 工作 。 

在 这 一 点 上 你 可 能 会 问 自己 ' 你 怎么 能 有 多 个 服务 器 监听 同一 主机 和 端口 ?尝试 部 署 多 个 实 

例 ， 肯 定 会 端口 冲突 ? 

Vert.x 确实 有 点 神奇 ， 如 

当 你 在 同一 个 主机 上 部 署 另 一 个 服务 器 ， 作 为 一 个 现 有 的 服务 器 ， 它 实际 上 并 没有 尝试 在 同 
一 个 主机 /端口 上 创建 一 个 新 的 服务 器 。 


相反 它 内 部 维护 只 是 一 台 服 务 器 ， 将 连接 通过 循环 的 方式 分 配 处 理 程序 。 


因此 Vert.x TCP 服务 部 署 可 以 超过 可 用 CPU 内 核 ， 每 个 实例 是 单个 线程 。 
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创建 TCP 客户 端 
最 简单 的 方法 来 创建 一 个 TCP 客户 端 ， 使 用 默认 选项 如 下 所 示 : 


NetClient client = vertx.createNetClient(); 


配置 TCP 客户 端 
如 果 你 不 想 使 用 默认 值 ， 则 创建 TCP 客户 端 时 ， 通 过 传 入 NetClientOptions 实 例 可 以 配置 


NetClientOptions options = new NetClientOptions().setConnectTimeout(10000); 
NetClient client - vertx.createNetClient(options); 


立 连 接 


要 连接 到 的 服务 器 可 以 使 用 connect， 指 定 端 口 和 服务 器 地 址 和 一 个 handler ，handler 包 念 
NetSocket 和 成 功 或 者 失败 的 结果 。 


NetClientOptions options = new NetClientOptions().setConnectTimeout(10000); 
NetClient client - vertx.createNetClient(options); 
client.connect(4321, "localhost", res -> ( 
if (res.succeeded()) { 
System.out.println("Connected!"); 
NetSocket socket - res.result(); 
) else { 
System.out.println("Failed to connect: " + res.cause().getMessage( )); 


配置 自动 重 连 


无 法 连接 可 以 配置 为 自动 重 连 。 配 置 setReconnectinterval 和 setReconnectAttempits. 


注意 目前 Vertx 不 会 尝试 重新 连接 ， 如 果 连 接 失败 ， 重 连 和 重 连 间隔 仅 适用 于 创建 初始 
连接 


o 


NetClientOptions options - new NetClientOptions(). 
setReconnectAttempts(10).//$3k;X dk 
setReconnectInterval(500)// £ #4 m 


NetClient client = vertx.createNetClient(options); 
默认 情况 下 ， 自 动 重 连 不 开启 。 


配置 服务 器 和 客户 端 使 用 SSL/TLS 

TCP 客户 端 和 服务 器 可 以 配置 使 用 TLS (安全 传输 层 协 议 ) -TLS 的 早期 版 本 被 称 为 SSL 。 
无 论 使 用 SSL/TLS 服 务 器 和 客户 端 Api 是 相同 的 ， 是 否 启 用 ， 通 过 NetClientOptions 

或 NetServerOptions 实 例 配 置 。 

在 服务 器 上 启用 SSL/TLS 

通过 ssl 启 用 SSL/TLS. 

默认 是 禁用 的 。 

为 服务 器 指定 密 钥 /证 书 

SSL/TLS 服 务 器 通常 提供 证 书 给 客户 以 验证 他 们 的 身份 。 

针对 服务 器 的 几 种 配置 证 书 / 密 铀 的 方式 : 

第 一 种 方法 是 通过 指定 Java 密 钥 存储 并 包含 证 书 和 私 钥 的 位 置 。 

Java 密 钥 存储 库 可 以 使 用 JDK 附 带 的 实用 程序 keytool 工 具 管 理 。 此 外 应 提供 密 钥 存储 库 的 密 


码 : 


NetServerOptions options = new NetServerOptions().setSsl(true).setKeyStoreOptions( 
new JksOptions(). 
setPath("/path/to/your/server-keystore.jks"). 
setPassword("password-of-your-keystore") 
); 


NetServer server = vertx.createNetServer (options); 


或 者 ， 你 可 以 把 你 自己 的 钥匙 储存 为 一 个 缓冲 区 ， 直 接 提 供 : 


Buffer myKeyStoreAsABuffer - vertx.fileSystem().readFileBlocking("/path/to/your/server 
-keystore.jks"); 
JksOptions jksOptions - new JksOptions(). 
setValue(myKeyStoreAsABuffer). 
setPassword("password-of-your-keystore"); 
NetServerOptions options - new NetServerOptions(). 
setSsl(true). 
setKeyStoreOptions(jksOptions); 
NetServer server - vertx.createNetServer(options); 


还 可 以 以 类 似 Jks 方式 Pkcs #12 RA (http://en.wikipedia.org/wiki/PKCS 12) 48 £f fit Ze 
载 密 铀 /证 书 ， 通 常 具有 .pfx 或 .p12 扩展 名 : 


NetServerOptions options = new NetServerOptions().setSsl(true).setPfxKeyCertOptions( 
new PfxOptions(). 
setPath("/path/to/your/server-keystore.pfx"). 
setPassword("password-of -your-keystore") 
); 


NetServer server = vertx.createNetServer(options); 


此 外 支持 缓冲 区 配置 : 


Buffer myKeyStoreAsABuffer = vertx.fileSystem().readFileBlocking("/path/to/your/server 
-keystore.pfx"); 
PfxOptions pfxOptions - new PfxOptions(). 
setValue(myKeyStoreAsABuffer). 
setPassword("password-of your -keystore"); 
NetServerOptions options - new NetServerOptions(). 
setSsl(true). 
setPfxKeyCertOptions(pfxOptions); 
NetServer server - vertx.createNetServer(options); 


另 一 种 方式 ， 分 别 使 用 ,pem 文件 提供 服务 器 私 钥 和 证 书 。 


NetServerOptions options = new NetServerOptions().setSsl(true).setPemKeyCertOptions( 
new PemKeyCertOptions(). 
setKeyPath("/path/to/your/server-key.pem"). 
setCertPath("/path/to/your/server-cert.pem") 
); 


NetServer server = vertx.createNetServer(options); 


此 外 支持 缓冲 区 配置 : 


Buffer myKeyAsABuffer - vertx.fileSystem().readFileBlocking("/path/to/your/server-key. 
pem"); 
Buffer myCertAsABuffer - vertx.fileSystem().readFileBlocking("/path/to/your/server-cer 
t.pem"); 
PemKeyCertOptions pemOptions = new PemKeyCertOptions(). 
setKeyValue(myKeyAsABuffer). 
setCertValue(myCertAsABuffer); 
NetServerOptions options - new NetServerOptions(). 
setSsl(true). 
setPemKeyCertOptions(pemOptions); 
NetServer server - vertx.createNetServer(options); 


请 牢记 ，pem 的 配置 ， 私 钥 是 不 加 密 的 。 

指定 信任 服务 器 

SSL /TLS 服 务 器 使 用 证 书 授权 可 以 以 验证 客户 端的 身份 。 

几 种 针对 服务 器 的 证 书 授权 的 配置 方法 : 

此 外 应 提供 密 钥 存储 库 的 密码 : 

Java trust 存 储 库 可 以 使 用 JDK 附 带 的 实用 程序 keytool 工 具 管理 。 


此 外 应 提供 trust 存 储 库 的 密码 : 


NetServerOptions options = new NetServerOptions(). 

setSsl(true). 

setClientAuth(ClientAuth.REQUIRED). 

setTrustStoreOptions( 

new JksOptions(). 

setPath("/path/to/your/truststore.jks"). 
setPassword("password-of-your-truststore") 

); 


NetServer server = vertx.createNetServer(options); 


或 者 ， 你 可 以 把 你 自己 的 trust 储 存 为 一 个 缓冲 区 ， 直 接 提供 : 


Buffer myTrustStoreAsABuffer - vertx.fileSystem().readFileBlocking("/path/to/your/trus 
tstore.jks"); 
NetServerOptions options - new NetServerOptions(). 
setSsl(true). 
setClientAuth(ClientAuth.REQUIRED). 
setTrustStoreOptions( 
new JksOptions(). 
setValue(myTrustStoreAsABuffer). 
setPassword("password-of-your-truststore") 
); 


NetServer server = vertx.createNetServer(options); 


还 可 以 以 类 似 Is 方式 Pkcs #12 格式 (http://en.wikipedia.org/wiki/PKCS_12) trust 存储 
加 载 密 铀 /证 书 ， 通 常 具 有 .pfx 或 .p12 扩展 名 : 


NetServerOptions options = new NetServerOptions(). 

setSsl(true). 

setClientAuth(ClientAuth.REQUIRED). 

setPfxTrustOptions( 

new PfxOptions(). 

setPath("/path/to/your/truststore.pfx"). 
setPassword("password-of-your-truststore") 

); 


NetServer server = vertx.createNetServer(options); 


此 外 支持 缓冲 区 配置 : 


Buffer myTrustStoreAsABuffer = vertx.fileSystem().readFileBlocking("/path/to/your/trus 
tstore.pfx"); 
NetServerOptions options - new NetServerOptions(). 
setSsl(true). 
setClientAuth(ClientAuth.REQUIRED). 
setPfxTrustOptions( 
new PfxOptions(). 
setValue(myTrustStoreAsABuffer). 
setPassword("password-of-your-truststore") 
); 


NetServer server = vertx.createNetServer(options); 


另 一 种 方式 ， 使 用 列表 的 .pem 文 件 提供 服务 器 证 书 授权 


NetServerOptions options - new NetServerOptions(). 
setSsl(true). 
setClientAuth(ClientAuth.REQUIRED). 
setPemTrustOptions( 
new PemTrustOptions(). 
addCertPath("/path/to/your/server-ca.pem") 
); 


NetServer server = vertx.createNetServer (options); 


此 外 支持 缓冲 区 配置 


Buffer myCaAsABuffer = vertx.fileSystem().readFileBlocking("/path/to/your/server-ca.pf 
x"); 
NetServerOptions options - new NetServerOptions(). 

setSsl(true). 

setClientAuth(ClientAuth.REQUIRED). 

setPemTrustOptions( 

new PemTrustOptions(). 
addCertValue(myCaAsABuffer) 


); 
NetServer server = vertx.createNetServer(options); 
在 客户 端 上 启用 SSL/TLS 


Net 客户 端 也 可 以 轻松 地 配置 为 使 用 SSL。 他 们 有 相同 的 API， 当 使 用 SSL 时 使 用 的 是 标准 
& sockets ° 


NetClient 调 用 setSSL(true) 函数 启用 SSL ° 
客户 端 信任 配置 
在 客户 端 ， 如 果 trustALI 设 置 为 true， 客 户 端 将 信任 所 有 的 服务 器 证 书 。 连 接 仍 将 被 加 密 ， 但 


这 种 模式 是 易 受 攻击 的 。 请 谨 懂 使 用 。 上 默认 值 为 false 。 


NetClientOptions options = new NetClientOptions(). 
setSsl(true). 
setTrustAll(true); 
NetClient client - vertx.createNetClient(options); 
如 果 未 设置 trustAll， 客 户 端 必 须 配 置 trust store 和 应 该 包含 该 客户 端 信任 的 服务 器 证 书 。 
同 服务 器 配置 ， 配 置 客户 端 信任 可 以 分 几 个 方面 : 


第 一 种 方法 是 通过 指定 包含 证 书 授权 Java trust-store 的 位 置 。 


这 只 是 标准 Java 密 钥 库 ， 密 钥 存 储 与 服务 器 端 相同 。 由 jks options 使 用 函数 path 设 置 的 客户 
端 trust-store 位 置 。 如 果 服 务 器 不 是 客户 端 信 任 存 储 区 中 的 连接 过 程 中 提供 的 证 书 ， 则 连接 党 
试 不 会 成 功 。 


NetClientOptions options = new NetClientOptions(). 
setSsl(true). 
setTrustStoreOptions( 
new JksOptions(). 
setPath("/path/to/your/truststore.jks"). 
setPassword("password-of-your-truststore") 
); 


NetClient client = vertx.createNetClient(options); 


此 外 支持 缓冲 区 配置 : 


Buffer myTrustStoreAsABuffer = vertx.fileSystem().readFileBlocking("/path/to/your/trus 
tstore.jks"); 
NetClientOptions options - new NetClientOptions(). 
setSsl(true). 
setTrustStoreOptions( 
new JksOptions(). 
setValue(myTrustStoreAsABuffer). 
setPassword("password-of-your-truststore") 
); 


NetClient client = vertx.createNetClient(options); 


还 可 以 以 类 似 Jks 方式 Pkcs #12 X (http://en.wikipedia.org/wiki/PKCS 12) trust 存储 
加 载 密 钥 /证 书 ， 通 常 具 有 .pfx 或 .p12 扩展 名 : 


NetClientOptions options = new NetClientOptions(). 
setSsl(true). 
setPfxTrustOptions( 
new PfxOptions(). 
setPath("/path/to/your/truststore.pfx"). 
setPassword("password-of-your-truststore") 
); 


NetClient client = vertx.createNetClient(options); 


此 外 支持 缓冲 区 配置 : 


Buffer myTrustStoreAsABuffer - vertx.fileSystem().readFileBlocking("/path/to/your/trus 
tstore.pfx"); 
NetClientOptions options - new NetClientOptions(). 
setSsl(true). 
setPfxTrustOptions( 
new PfxOptions(). 
setValue(myTrustStoreAsABuffer). 
setPassword("password-of-your-truststore") 
); 


NetClient client = vertx.createNetClient(options); 


另 一 种 方式 ， 使 用 列表 的 .pem 文 件 提 供 服务 器 证 书 授权 


NetClientOptions options = new NetClientOptions(). 
setSsl(true). 
setPemTrustOptions( 
new PemTrustOptions(). 
addCertPath("/path/to/your/ca-cert.pem") 
); 


NetClient client = vertx.createNetClient(options); 


此 外 支持 缓冲 区 配置 : 


Buffer myTrustStoreAsABuffer = vertx.fileSystem().readFileBlocking("/path/to/your/ca-c 
ert.pem"); 
NetClientOptions options - new NetClientOptions(). 

setSsl(true). 

setPemTrustOptions( 

new PemTrustOptions(). 
addCertValue(myTrustStoreAsABuffer) 
); 


NetClient client = vertx.createNetClient(options); 


为 客户 端 指定 密 乌 / 证 书 


如 果 服 务 器 要 求 客户 端 身份 验证 ， 然 后 连接 时 ， 客 户 端 必须 向 服务 器 提交 它 自 己 的 证 书 。 客 
户 端 可 以 配置 几 个 方面 : 


第 一 种 方法 是 通过 指定 Java 密 铀 库 包 含 密 钥 和 证 书 的 位 置 。 这 是 只 是 常规 Java 的 密 钥 存储 
库 。 客 户 端 密 钥 库 位 置 是 通过 使 用 函数 path 上 jks options 设 置 . 


NetClientOptions options = new NetClientOptions().setSsl(true).setKeyStoreOptions( 
new JksOptions(). 
setPath("/path/to/your/client-keystore.jks"). 
setPassword("password-of -your-keystore") 
); 


NetClient client = vertx.createNetClient(options); 


此 外 支持 缓冲 区 配置 : 


Buffer myKeyStoreAsABuffer = vertx.fileSystem().readFileBlocking("/path/to/your/client 
-keystore.jks"); 
JksOptions jksOptions - new JksOptions(). 
setValue(myKeyStoreAsABuffer). 
setPassword("password-of-your-keystore"); 
NetClientOptions options - new NetClientOptions(). 
setSsl(true). 
setKeyStoreOptions(jksOptions); 
NetClient client - vertx.createNetClient(options); 


还 可 以 以 类 似 Is 方式 Pkcs #12 XA (http://en.wikipedia.org/wiki/PKCS 12) trust 存储 
加 载 密 铀 /证 书 ， 通 常 具 有 .pfx 或 .p12 扩展 名 : 


NetClientOptions options = new NetClientOptions().setSsl(true).setPfxKeyCertOptions( 
new PfxOptions(). 
setPath("/path/to/your/client-keystore.pfx"). 
setPassword("password-of -your-keystore") 
); 


NetClient client = vertx.createNetClient(options); 


此 外 支持 缓冲 区 配置 : 


Buffer myKeyStoreAsABuffer = vertx.fileSystem().readFileBlocking("/path/to/your/client 
-keystore.pfx"); 
PfxOptions pfxOptions - new PfxOptions(). 
setValue(myKeyStoreAsABuffer). 
setPassword("password-of -your-keystore"); 
NetClientOptions options - new NetClientOptions(). 
setSsl(true). 
setPfxKeyCertOptions(pfxOptions); 
NetClient client - vertx.createNetClient(options); 


另 一 种 方式 ， 分 别 使 用 ,pem 文件 提供 服务 器 私 钥 和 证 书 。 


NetClientOptions options = new NetClientOptions().setSsl(true).setPemKeyCertOptions( 
new PemKeyCertOptions(). 
setKeyPath("/path/to/your/client-key.pem"). 
setCertPath("/path/to/your/client-cert.pem") 
); 


NetClient client = vertx.createNetClient(options); 


此 外 支持 缓冲 区 配置 : 


Buffer myKeyAsABuffer - vertx.fileSystem().readFileBlocking("/path/to/your/client-key. 
pem"); 
Buffer myCertAsABuffer - vertx.fileSystem().readFileBlocking("/path/to/your/client-cer 
t.pem"); 
PemKeyCertOptions pemOptions = new PemKeyCertOptions(). 
setKeyValue(myKeyAsABuffer). 
setCertValue(myCertAsABuffer); 
NetClientOptions options - new NetClientOptions(). 
setSsl(true). 
setPemKeyCertOptions(pemOptions); 
NetClient client - vertx.createNetClient(options); 


请 牢记 ，pem 的 配置 ， 私 铀 是 不 加 密 的 。 
吊销 认证 授权 


被 吊销 的 证 书 不 再 应 信任 ， 信 任 可 以 配置 为 使 用 证 书 吊 销 列表 (CRL)。crlPath 配 置 要 使 用 的 
crl 列表 : 


NetClientOptions options = new NetClientOptions(). 
setSsl(true). 
setTrustStoreOptions(trustOptions). 
addCriPath("/path/to/your/crl.pem"); 

NetClient client - vertx.createNetClient(options); 


此 外 支持 缓冲 区 配置 : 


Buffer myCrlAsABuffer = vertx.fileSystem().readFileBlocking("/path/to/your/crl.pem"); 
NetClientOptions options - new NetClientOptions(). 

setSsl(true). 

setTrustStoreOptions(trustOptions). 

addCriValue(myCrlAsABuffer); 
NetClient client - vertx.createNetClient(options); 


配置 加 密 套 件 


默认 情况 下 ，TLS 配 置 将 使 用 JVM 运 行 Vert.x. 的 加 密 套 件 这 种 
行 配置 : 


器 


并 


芍 码 套件 可 以 用 一 组 启用 密码 进 


NetServerOptions options - new NetServerOptions(). 
setSsl(true). 
setKeyStoreOptions(keyStoreOptions). 
addEnabledCipherSuite("ECDHE-RSA-AES128-GCM-SHA256"). 
addEnabledCipherSuite("ECDHE-ECDSA-AES128-GCM-SHA256"). 
addEnabledCipherSuite("ECDHE-RSA-AES256 -GCM-SHA384"). 
addEnabledCipherSuite("CDHE-ECDSA-AES256 -GCM-SHA384" ) ; 

NetServer server - vertx.createNetServer(options); 


加 密 套 件 可 以 在 NetServerOptions 或 NetClientOptions 配 置 中 指定 。 
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最 简单 的 方法 来 创建 一 个 HTTP 服务 器 ， 所 有 选项 使 用 默认 的 。 如 下 所 示 : 


HttpServer server = vertx.createHttpServer(); 


配置 HTTP 7R 2-8 
如 果 你 不 想 使 用 默认 值 ， 创 建 服务 器 时 可 以 通过 传 入 一 个 HttpServerOptions 实 例 配 置 : 


HttpServerOptions options = new HttpServerOptions().setMaxWebsocketFrameSize(1000000); 


HttpServer server - vertx.createHttpServer(options); 


启动 服务 器 监听 
使 用 listen 告 诉 服务 器 以 监听 传 入 的 请 求 。 


在 选项 中 指定 的 主机 和 端口 : 


HttpServer server = vertx.createHttpServer(); 
server.listen(); 


或 在 调用 listen 中 指定 的 主机 和 端口 ， 忽 略 配置 选 项 : 


HttpServer server = vertx.createHttpServer(); 
server.listen(8080, "myhost.com"); 


默认 主机 是 0.0.0.0 ^ ' 监 听 所 有 可 用 的 地 址 ' ， 默 认 端 口 是 80. 
实际 的 绑 定 是 异步 的 ， 所 以 服务 器 可 能 不 会 实际 被 监听 ， 直 到 一 段 时 间 后 ， 调 用 返回 。 


如 果 想 要 listen 实 际 监听 后 通知 你 ， 可 以 提供 listen 调 用 处 理 程序 。 例 如 : 


HttpServer server - vertx.createHttpServer(); 
server.listen(8080, "myhost.com", res -> ( 
if (res.succeeded()) 1 
System.out.println("Server is now listening!"); 
} else ( 
System.out.println("Failed to bind!"); 
} 
}); 


收 到 传 入 请 求 通知 
若 要 请 求 到 达 时 通知 ， 需 要 设置 requestHandler: 


HttpServer server = vertx.createHttpServer(); 
server.requestHandler(request -> ( 
// Handle the request in here 


15 
处 理 请 求 


当 请 求 到 达 时 ， 则 该 请 求 调用 处 理 程序 传递 HttpServerRequest 的 一 个 实例 。 此 对 象 所 表示 的 
服务 器 端的 HTTP 请 求 。 


当 请 求 headers 已 完全 读 取 时 ， 将 调用 该 处 理 程序 。 
如 果 该 请 求 包含 一 个 body， 该 body 将 到 达 服 务 器 ， 一 段 时 间 后 请 求 处 理 程 序 被 调用 。 
服务 器 请 求 对 象 可 以 获取 uri、path、params 和 headers 等 。 


每 个 服务 器 请 求 对 象 是 与 一 台 服 务 器 的 响应 对 象 相 关联 。 使 用 response 来 获取 对 
HttpServerResponse 对 象 。 


这 里 是 一 个 简单 的 例子 ， 服 务 器 处 理 请 求 和 回复 "hello world" 。 


vertx.createHttpServer().requestHandler(request -> { 
request.response().end("Hello world"); 
)).listen(8080); 


请 求 的 版 本 
HTTP 请 求 中 指定 的 版 本 ， 可 以 用 version 获 取 
请 求 方法 


method 用 于 获得 请 求 的 HTTP 方法。( 即 是 GET，POST 、PUT 、DELETE ^ HEAD ` 
OPTIONS €) ° 


请 求 的 URI 

使 用 uri 来 获取 请 求 的 URI 。 

注意 ， 这 是 通过 在 HTTP 请 求 中 ， 实 际 URI， 它 几乎 总 是 相对 URI o 
URI 是 在 HTTP 规 范 的 5.1.2 节 中 定义 - 请 求 URI 
请 求 路 径 

使 用 path 返 回 URI 的 路 径 

例如 ， 如 果 请 求 URI 只 是 : 
a/b/c/page.html?parami-abc&param2-xyz 

那么 ， 路 径 会 

/a/b/c/page.html 

请 求 查询 

使 用 query 返 回 的 URI 的 查询 部 分 

例如 ， 如 果 请 求 URI 只 是 : 
a/b/c/page.html?parami-abc&param2-xyz 

那么 ， 该 查询 会 

parami-abc&param2-xyz 

ib 3k headers 

使 用 headers 方 法 来 返回 的 HTTP 请 求 headers 。 


这 将 返回 一 个 实例 MultiMap- 就 像 一 个 普通 的 map 或 Hash， 但 允许 多 个 值 的 同一 键 -这 是 因为 
HTTP 允许 多 个 header 值 用 相同 的 密 钥 。 


key 不 区 分 大 小 写 ， 这 就 意味 着 您 可 以 执行 以 下 操作 : 


MultiMap headers = request.headers(); 


// Get the User-Agent: 
System.out.println("User agent is " + headers.get("user-agent")); 


// You can also do this and get the same result: 
System.out.println("User agent is " + headers.get("User-Agent")); 


请 求 参数 


使 用 params 返 回 的 HTTP 请 求 参 数 。 
就 像 headers 这 返回 的 MultiMap 实 例 ， 可 以 有 多 个 参数 具有 相同 的 名 称 。 


路 径 后 的 请 求 URI 是 请 求 参数 。 例 如 ， 如 果 URI 


/page.html?parami-abc&param2-xyz 


parami: 'abc' 
param2: 'xyz 


请 注意 这 些 请 求 参数 从 请 求 的 URL。 如 果 您 有 已 作为 体内 的 multi-part/form-data 请 求 提交 
HTML 表单 提交 的 一 部 分 发 送 的 窗 体 属 性 然后 他 们 将 不 出 现在 这 里 的 params 。 


请 注意 ， 这 些 请 求 参 数 从 请 求 的 URL 中 获取 。 如 果 你 的 form 属 性 为 multi-part/form-data 请 求 
的 话 ， 参 数 不 会 出 现在 这 里 ， 会 包含 在 body 中 提交 发 送 。 


远程 地 址 
请 求 的 发 送 者 的 地 址 可 以 通过 remoteaddress 获 取 。 
绝对 URI 


传 入 的 HTTP 请 求 的 URI 是 通常 相对 。 如 果 想 要 检索 对 应 于 该 请 求 的 绝对 URI， 可 以 
用 absoluteURI 


结束 处 理 程序 
当 整 个 ， 包 括 任何 body 已 完全 读 取 请 求 时 ， 将 调用 endHandler 请 求 。 
从 请 求 正 body 读 取 数 据 


通常 一 个 HTTP 请 求 包含 我 们 想 要 读 取 的 body。 前 面 所 提 到 的 请 求 处 理 程序 仅仅 有 headers， 
这 里 并 没有 body 。 

这 是 因为 body 可 能 会 非常 大 (例如 一 个 文件 上 传 )， 我 们 通常 不 不 会 吧 缓 冲 的 整个 body 放 在 内 
存 中 交 给 你 ， 因 为 那 将 导致 服务 器 内 存 用 尽 。 


若 要 接收 body， 您 可 以 使 用 handler 请 求 ， 调 用 后 ， 会 有 请 求 body 到 达 。 下 面 是 一 个 示例 : 


request.handler(buffer -> ( 

System.out.println("I have received a chunk of the body of length " + buffer.length( 
); 
15; 


传递 到 handler 的 对 象 是 一 个 Buffer， 该 handler 可 以 调用 多 次 ， 当 数据 到 达 时 从 网 络 ， 根 据 
body 的 大 小 。 


在 某 些 情况 下 (例如 如 果 body 很 小 ) 想 要 在 内 存 中 缓存 整个 body 如 下 所 示 : 


Buffer totalBuffer = Buffer.buffer(); 


request.handler(buffer -» ( 
System.out.println("I have received a chunk of the body of length " + buffer.length( 


)); 
totalBuffer .appendBuffer (buffer); 
15 


request.endHandler(v -» ( 
System.out.println("Full body received, length = " + totalBuffer.length()); 


3): 


这 是 这 种 常见 的 情况 ，Vert.x 提供 bodyHandler 来 为 你 做 这 个 。bodyHandler 收 到 所 有 的 body: 


request.bodyHandler(totalBuffer -> ( 
System.out.println("Full body received, length = " + totalBuffer.length()); 


3); 
Pumping requests 


il Rat S X ReadStream ， 所 以 你 可 以 pump 请 求 body 到 任何 WriteStream 实 例 。 


处 理 HTML 表单 

HTML 表 单 可 以 提交 application/x-www-form-urlencoded 或 multipart/form-data 内 容 类 型 。 
对 于 url 编码 形式 ， 像 正常 的 查询 参数 一 样 ， 把 表单 属性 编码 在 Url 中 。 
multi-part 表 单 在 请 求 body 中 编码 ， 因 此 不 可 用 直到 从 wire 读 取 了 整个 body 。 

Multi-part 表单 还 可 以 包含 文件 上 传 。 


如 果 您 想 要 获取 的 属性 是 multi-part 的 形式 ， 得 到 这 种 表单 之 前 ， 通 过 调用 setExpectMultipart 
设置 为 ttue， 告 诉 Vert.x 你 期 望 的 body 是 read，， 然 后 你 应 该 使 用 formAttributes 获 取 » i JR 
所 有 body 的 属性 


server.requestHandler(request -> ( 
request.setExpectMultipart(true); 
request.endHandler(v -» ( 
// The body has now been fully read, so retrieve the form attributes 
MultiMap formAttributes - request.formAttributes(); 


3); 
}); 


处 理 表单 文件 上 传 

Vert.x 还 可 以 处 理 在 multi-part 请 求 body 中 编码 文件 上 传 。 

接收 文件 上 传 ， 告 诉 Vert.x 期 望 multi-part 表 单 形式 并 要 求 设置 uploadHandler。 
每 个 上 传 到 服务 器 上 ， 此 handler 将 调用 一 次 。 


传递 到 handler 的 对 象 是 一 个 HttpServerFileUpload 实 例 。 


server.requestHandler(request -> ( 
request.setExpectMultipart(true); 
request.uploadHandler(upload -> { 
System.out.println("Got a file upload " + upload.name()); 


3); 
2p 


上 传 的 文件 可 能 会 很 大 ， 我 们 不 提供 单个 缓冲 区 上 传 整 个 数据 ， 因 为 这 可 能 导致 内 存 消耗 殖 
尽 ， 取 而 代 之 的 是 ， 上 传 的 数据 在 块 中 收 到 : 


request.uploadHandler(upload -> { 
upload.handler(chunk -> { 
System.out.println("Received a chunk of the upload of length " + chunk.length()); 


3); 
}); 


上 传 对 象 是 ReadStream ， 所 以 你 可 以 pump 请 求 body 到 任何 WriteStream 实 例 。 


如 果 你 只 是 想 要 上 传 文件 到 磁盘 ， 你 可 以 使 用 streamToFileSystem: 


request.uploadHandler(upload -> ( 
upload.streamToFileSystem("myuploads directory/" + upload.filename()); 


H; 


警告 确保 您 在 一 个 生产 系统 中 检查 文件 ， 以 避免 恶意 客户 端 将 文件 上 传 到 您 的 文件 系 


统 。 查 看 更 多 信息 的 安全 说 明 。 


发 送 返回 响应 

服务 器 的 响应 对 象 是 HttpServerResponse 的 实例 和 所 得 的 请 求 response. 
响应 对 象 用 于 写 回 HTTP 客户 端的 响应 。 

设置 状态 代码 和 消息 

response 的 默认 HTTP 状态 码 是 200， 表 示 OK. 

使 用 setStatusCode 来 设置 不 同 的 代码 。 

您 还 可 以 使 用 setStatusMessage 指 定 一 个 自 定义 的 状态 消息 . 
如 果 您 不 指定 一 条 状态 消息 ， 将 使 用 默认 的 状态 代码 。 

写 入 HTTP responses (响应 ) 

使 用 一 个 write 操 作 ， 将 数据 写 入 HTTP responses。 

这 些 可 以 在 响应 结束 之 前 多 次 调用 。 可 以 以 下 面 几 种 方法 调用 : 


用 一 个 缓冲 区 : 


HttpServerResponse response = request.response( ); 
response.write(buffer); 


用 一 个 字符 串 。 在 这 种 情况 下 将 默认 使 用 UTF-8 编 码 。 


HttpServerResponse response = request.response( ); 
response.write("hello world!"); 


使 用 一 个 字符 串 和 编码 。 在 本 例 的 字符 串 将 使 用 指定 的 编码 。 


HttpServerResponse response = request.response( ); 
response.write("hello world!", "UTF-16"); 
写 入 responses 是 异步 的 ， 在 写 入 队列 后 立即 返回 。 
如 果 你 只 是 写 一 个 字符 串 或 缓存 HTTP response, 你 可 以 写 它 和 调用 end 结 束 response 


在 响应 头 第 一 个 调用 正在 被 写 入 结果 的 响应 第 一 次 调用 将 写 入 结果 正在 被 写 入 到 响应 响应 
头 。 因 此 ， 如 果 您 不 使 用 HTTP 分 块 然后 之 前 ， 必 须 设置 Content-Length 标 头 写 的 反应 ， 
为 它 否 则 就 太 晚 了 。 如 果 您 使 用 的 HTTP 分 块 你 不 必 担 心 。 


第 一 次 调用 写 结果 的 响应 头 被 写 入 响应 。 因 此 ,如 果 你 不 使 用 HTTP 分 块 ， 那 么 header， 你 必 
须 设 置 响应 的 Content-Length。 如 果 您 使 用 HTTP 分 块 你 不 必 担 心 。 


结束 HTTP responses 
一 旦 你 完成 了 HTTP responses 你 应 该 end 它 。 
这 可 以 有 以 下 几 种 方式 : 


不 带 任 何 参数 ，response 是 只 是 结束 。 


HttpServerResponse response = request.response( ); 
response.write("hello world!"); 
response.end(); 


pu QE METUS 在 这 种 情况 下 ， 首 先 用 字符 串 写 入 缓冲 
区 ， 然 后 和 不 带 参 数 的 一 样 。 例 如 


HttpServerResponse response = request.response( ); 
response.end("hello world!"); 


关闭 底层 连接 
使 用 close 关闭 底层 的 TCP 连接 . 
短 连 接 在 response 结束 时 ， vert.x 将 自动 关闭 。 


长 连接 的 Vert.x 默认 情况 下 是 不 会 自动 的 关闭 。 如 果 你 希望 连接 保持 到 空闲 时 间 后 关闭 ， 使 
用 setldleTimeout 方法 配置 


设置 response headers 


可 以 将 HTTP response headers 通过 response 直接 添加 到 headers: 


HttpServerResponse response = request.response(); 
MultiMap headers - response.headers(); 
headers.set("content-type", "text/html"); 
headers.set("other-header", "wibble"); 


或 者 你 可 以 使 用 putHeader 


HttpServerResponse response = request.response( ); 
response.putHeader("content-type", "text/html").putHeader("other-header", "wibble"); 


Headers 必须 添加 在 所 有 写 入 response body 3j » 


43k HTTP 响应 和 传输 
Vert.x 支持 HTTP 分 块 传输 编码 . 
表示 输出 的 内 容 长 度 不 能 确定 。 


把 HTTP response 设置 为 分 块 模式 ， 如 下 所 示 : 


HttpServerResponse response = request.response(); 
response.setChunked(true); 


默认 值 为 非 分 块 。 在 分 块 模式 下 ， 每 次 调用 write 调用 时 ， 就 会 写 出 一 个 新 的 HTTP H e 


当 在 分 块 模式 中 你 也 可 以 写 入 HTTP response 传输 到 response。 实 际 上 ， 实际 上 写 入 响 
应 的 最 后 块 。 


若 要 添加 trailers 到 response， 直 接 添加 到 trailers. 


HttpServerResponse response = request.response( ); 
response.setChunked(true); 

MultiMap trailers - response.trailers(); 
trailers.set("X-wibble", "woobble").set("X-quux", "flooble"); 


或 使 用 putTrailer. 


HttpServerResponse response = request.response(); 
response.setChunked(true); 


response.putTrailer("X-wibble", "woobble").putTrailer("X-quux", "flooble"); 
直接 从 磁盘 或 类 路 径 (classpath) 提供 文件 服务 


如 果 你 正在 编写 一 个 Web 服 务 器 ， 使 用 AsyncFile 打 开 磁 盘 上 的 文件 并 注入 到 HTTP 
response ° 


或 者 你 可 以 一 气 呵 成 ， 使 用 readFile 加 载 并 直接 写 入 响应 。 


AIN > Vert.x 提供 了 一 种 方法 ， 可 以 从 磁盘 或 者 文件 系 od a response。 由 底层 操作 系 
统 支持 ， 这 可 能 在 OS 中 直接 从 文件 到 套 接 字 传 送 字 节 ， 而 无 需 通 过 用 户 空间 (user-space ) 
复制 。 


对 于 大 文件 使 用 SendFile， 通 常 更 有 效 ， 但 小 文件 可 能 较 慢 。 


下 面 是 使 用 sendFile， 提 供 了 一 个 非常 简单 的 Web 服 务 器 : 


vertx.createHttpServer().requestHandler(request -> ( 
String file - ""; 
if (request.path().equals("/")) 1 
file - "index.html"; 
) else if (!request.path().contains("..")) 1 
file - request.path(); 
} 
request.response().sendFile("web/" + file); 
}).listen(8080); 


发 送 的 文件 是 异步 的 ,可 能 无 法 马上 返回 。 如 果 你 想 要 该 文件 写 入 完成 通知 ， 可 以 使 
Fl sendFile 


如 果 你 在 使 用 的 HTTPS 使 用 sendFile 会 通过 用 户 空 间 ， 因 为 如 果 内 核 将 数据 直接 从 磁 
盘 对 套 接 字 ,没有 机 会 给 应 用 任何 加 密 。 


BES 
警告 


如 果 你 要 直接 使 用 Vert.x 5 web 服务 器 ， 小 心 用 户 访 问 其 他 文件 路 径 ， 使 用 Vert.x Web 


当 只 需要 一 个 文件 片段 ， 可 以 给 定 从 某 字 节 开 发 ， 可 以 通过 下 面 达 到 : 


vertx.createHttpServer().requestHandler(request -> { 
long offset = 0; 
try ( 
offset - Long.parseLong(request.getParam("start")); 
) catch (NumberFormatException e) { 
// error handling... 


long end - Long.MAX VALUE; 
try ( 

end - Long.parseLong(request.getParam("end")); 
catch (NumberFormatException e) { 

// error handling... 


request.response().sendFile("web/mybigfile.txt", offset, end); 
)).listen(8080); 


如 果 想 要 发 送 的 文件 从 偏 移 量 开始 到 结束 ， 您 不 需要 提供 ， 在 这 种 情况 下 你 可 以 这 么 做 : 


vertx.createHttpServer().requestHandler(request -> ( 
long offset - 0; 
try { 
offset - Long.parseLong(request.getParam("start")); 
) catch (NumberFormatException e) { 
// error handling... 


} 


request.response().sendFile("web/mybigfile.txt", offset); 
)).listen(8080); 


注入 responses 


服务 器 response 是 一 个 WriteStream 实 例 ， 可 以 从 任何 ReadStream 注 入 ， 例 如 
AsyncFile，NetSocket，WebSocket 或 HttpServerRequest ° 


这 是 一 个 PUT 请 求 body 返 回响 应 的 例子 ， 使 用 pump， 即 使 HTTP 请 求 body 比 内 存 大 的 多 ， 也 
能 正常 工作 : 


vertx.createHttpServer().requestHandler(request -» ( 
HttpServerResponse response - request.response(); 
if (request.method() -- HttpMethod.PUT) { 
response.setChunked(true); 
Pump.pump(request, response).start(); 
request.endHandler(v -» response.end()); 
) else { 
response.setStatusCode(400).end(); 


} 
}).listen(8080); 


HTTP 压缩 

Vert.x 带 有 HTTP 压缩 开 箱 即 用 支持 。 

这 意味 着 在 发 送 回 客户 端 之 前 能 自动 压缩 响应 的 主体 。 

如 果 客 户 端 不 支持 HTTP 压缩 ， 将 没有 压缩 body 响应 发 送 回 。 

这 可 以 同时 处 理 支持 HTTP 压缩 的 客户 端 和 那些 不 支持 HTTP 压缩 的 客户 端 。 
若 要 启用 压缩 ， 使 用 setCompressionSupported 配 置 。 

默认 情况 下 不 启用 压缩 。 


当局 用 HTTP 压缩 ， 服 务 器 将 检查 客户 端 是 否 包括 Accept-Encoding 的 报头 ， 它 包含 支持 的 压 
缩 方式 。 常 用 的 有 deflate 和 gzip(Web 服 务 器 处 理 HTTP 压 缩 之 gzip、deflate 压 缩 )。Vert.x 两 
者 都 支持 。 


如 果 服 务 器 将 自动 压缩 与 一 个 支持 压缩 响应 正文 中 的 并 将 其 发 送 回 客 户 端 ， 就 找到 这 种 头 。 
如 果 找 到 这 样 的 报头 ， 服 务 器 将 自动 压缩 发 送 回 客户 端 。 


要 知道 压缩 可 能 能 够 减少 网 络 流量 ， 但 是 是 需要 消耗 更 多 的 CPU 。 
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创建 HTTP 客户 端 
使 用 默认 选项 创建 一 个 HttpClient 实 例 ， 如 下 所 示 : 


HttpClient client = vertx.createHttpClient(); 


果 您 想 要 在 创建 时 配置 客户 端的 选项 ， 如 下 所 示 : 


HttpClientOptions options = new HttpClientOptions().setKeepAlive(false); 
HttpClient client - vertx.createHttpClient(options); 


发 出 请 求 
Http 客户 端 非常 灵活 ， 可 以 用 各 种 方式 请 求 。 


http 客户 端 经 常 需要 将 许多 T 。 为 了 避免 每 次 发 出 请 求 需 要 重复 配 
置 主机 /端口 ， 您 可 以 配置 客户 端的 默认 主机 / 端 


HttpClientOptions options = new HttpClientOptions().setDefaultHost("wibble.com"); 
// Can also set default port if you want... 
HttpClient client - vertx.createHttpClient(options); 
client.getNow("/some-uri", response -> { 
System.out.println("Received response with status code " + response.statusCode( )); 


3); 


或 者 可 以 指定 单个 请 求 的 主机 /端口 。 


HttpClient client = vertx.createHttpClient(); 


// Specify both port and host name 
client.getNow(8080, "myserver.mycompany.com", "/some-uri", response -> { 
System.out.println("Received response with status code " + response.statusCode( )); 


3); 


// This time use the default port 80 but specify the host name 
client.getNow("foo.othercompany.com", "/other-uri", response -» ( 
System.out.println("Received response with status code " + response.statusCode()); 


3); 


没有 请 求 body 简 单 的 请 求 


通常 情况 下 ， 你 会 想 要 与 没有 请 求 body 的 HTTP 请 求 。 这 通常 是 HTTP GET > OPTIONS Z€ 
HEAD 请 求 。 


这 是 Vert.x http 客户 端的 最 简单 方法 ， 使 用 前 缓 与 Now 的 方法 。 例 如 getNow。 
这 些 方法 创建 HTTP 请 求 ， 并 在 单个 方法 调用 发 送 ， 让 你 提供 一 个 处 理 程序 ， 将 与 HTTP 响 应 
时 调用 它 回来 。 

HttpClient client = vertx.createHttpClient(); 


// Send a GET request 
client.getNow("/some-uri", response -» ( 
System.out.println("Received response with status code " + response.statusCode()); 


3) 


// Send a GET request 
client.headNow("/other-uri", response -> ( 
System.out.println("Received response with status code " + response.statusCode()); 


3); 


xz 


Ai 5 3-38 t) requests 
不 知道 想 要 发 送 请 求 方法 ， 和 运行 时 才 知 道 。 这 个 用 例 我 们 提供 通用 请 求 方法 例如 request， 可 
以 在 运行 时 指定 HTTP 方法 : 

HttpClient client = vertx.createHttpClient(); 


client.request(HttpMethod.GET, "some-uri", response -> ( 
System.out.println("Received response with status code " + response.statusCode( )); 


3).end(); 
client.request(HttpMethod.POST, "foo-uri", response -> ( 


System.out.println("Received response with status code " + response.statusCode( )); 
J).end("some-data"); 


编写 请 求 主体 (bodies) 
有 时 想 要 在 requests 里 含有 body， 或 者 想 写 请 求 的 headers。 


可 以 使 用 post 方 法 ， 或 者 普通 的 request 方 法 


这 些 方法 发 送 的 请 求 不 会 立即 返回 ， 而 是 返回 HttpClientRequest 实 例 ， 用 于 写 入 body 和 
header ° 


下 面 是 一 些 写 入 body 和 header 的 POST 请 求 的 例子 : 


HttpClient client - vertx.createHttpClient(); 


HttpClientRequest request = client.post("some-uri", response -> { 
System.out.println("Received response with status code " + response.statusCode()); 


3); 


// Now do stuff with the request 
request.putHeader("content-length", "1000"); 
request.putHeader("content-type", "text/plain"); 
request.write(body); 


// Make sure the request is ended when you're done with it 
request.end(); 


// Or fluently: 


client.post("some-uri", response -> { 

System.out.println("Received response with status code " + response.statusCode( )); 
)).putHeader("content-length", "1000").putHeader("content-type", "text/plain").write(b 
ody).end(); 


// Or event more simply: 
client.post("some-uri", response -> { 


System.out.println("Received response with status code " + response.statusCode()); 
)).putHeader("content-type", "text/plain").end(body); 


默认 Utf-8 编 码 : 


request.write("some data"); 


// Write string encoded in specific encoding 
request.write("some other data", "UTF-16"); 


// Write a buffer 

Buffer buffer = Buffer.buffer(); 
buffer.appendInt(123).appendLong(2451); 
request.write(buffer); 


如 果 你 的 HTTP 请 求 只 写 入 单个 字符 串 或 缓冲 区 ， 你 可 以 写 它 和 结束 end 元 数 单一 调用 中 的 请 
求 o 


request.end("some simple data"); 
// Write buffer and end the request (send it) in a single call 


Buffer buffer - Buffer.buffer().appendDouble(12.34d).appendLong(4321); 
request.end(buffer); 


当 你 写 到 一 个 请 求 时 ，write 第 一 次 调用 会 导致 写 入 网 络 的 请 求 标 头 。 

实际 的 写 操 作 是 异步 的 之 前 一 段 时 间 后 调用 已 返回 , 不 是 可 能 发 生 。 

非 分 块 请 求 正 文 与 HTTP 请 求 需要 要 提供 的 Content-Length 标 头 。 

因此 ， 如 果 您 不 使 用 分 块 的 HTTP 然后 之 前 ， 必 须 设置 Content-Length 标 头 写 入 请 求 ， 否 则 
它 将 太 述 了 。 

如 果 您 正在 调用 接受 字符 串 或 缓冲 区 的 end 方 法 之 一 然后 Vert.x 将 自动 计算 并 设置 Content- 
Length 标 头 在 写 请 求 正文 之 前 。 

如 果 您 使 用 的 HTTP. 分 块 Content-Length 标 头 不 是 必需 的 所 以 你 不 需要 计算 的 前 期 的 大 小 。 
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